dceky

A Cypress-based testing framework by Harvard DCE

Additional Docs

| Doc | Description | | --- | --- | | Writing Your First Test | Where tests live, the *.ky.ts naming rule, and a walkthrough of a basic test | | Profiles | Per-environment configuration: creating profiles, the Default profile, baseURL, and viewports | | Globals | The three globals files, dependent (dependsOn) values, and reading values in tests | | Global Credentials | Storing and using secure values like usernames, passwords, and tokens | | Globals and Profiles Configuration | How globals and profiles are merged and resolved internally | | Reports | The results folder, HTML reports, and failure screenshots produced by headless runs | | Command Reference | Full list of built-in ky. commands |

Getting Started

It's easy to use ky as your testing framework. To get started, follow these steps:

1. Create a New NPM Project

1. Create a Git repo and clone it
2. Initialize the project using npm init and fill out the questions in the wizard

2. Install and Configure Cypress

Install Cypress: npm i --save-dev cypress

Configure Cypress:

1. Use npx cypress open
2. Choose "E2E"
3. On the configuration page, simply click "Continue"
4. When you get to the browser chooser, close Cypress

From this point onward, you won't run cypress directly

3. Install and Set Up Ky

Install ky: npm i --save-dev dceky

Set up ky: npm run ky:setup

You'll have a bunch of changes to commit and push. Do that now.

Using Ky

Start Ky Tests: npm run ky:start

To start running ky tests, use one of these two options:

1. Run npm run ky:start and follow the chooser prompts.
2. Set environment variables before running npm run ky:start, either in your shell or in a .env file at the project root.

The chooser guides you through whether tests run visibly or headless, which profile(s) to use, which browser(s) to use, which e2e test folder to run, the "Num Test Files in Parallel Per Combo", and the "Num Combos in Parallel" for headless runs.

To set environment variables directly in your shell, run:

HEADLESS=true BROWSER=chrome,webkit PROFILE=Stage E2E_TEST_FOLDER=Activities THREADS_PER_COMBO=2 NUM_COMBOS_IN_PARALLEL=1 npm run ky:start

Or create a .env file:

HEADLESS=true
BROWSER=chrome,webkit
PROFILE=Stage
E2E_TEST_FOLDER=Activities
THREADS_PER_COMBO=2
NUM_COMBOS_IN_PARALLEL=1

Environment variables:

| Variable | Description | | --- | --- | | HEADLESS | Set to true to run without opening the Cypress UI. Set to false to run visibly. If omitted, ky asks in the chooser. | | BROWSER | Browser(s) to use for headless runs, as a comma-separated list such as chrome,webkit. Available browsers are chrome, webkit, edge, and firefox. If omitted during a headless run, ky asks in the chooser. | | PROFILE | Profile(s) to run, as a comma-separated list such as Stage or Stage,Prod. Visible runs use one profile; headless runs can use multiple. If omitted, ky asks in the chooser. | | E2E_TEST_FOLDER | E2E test folder to run for headless runs. Use a folder path under cypress/e2e, such as Activities or Activities/Respond. Use all, *, or . to run all e2e tests. If omitted, ky asks in the chooser. | | THREADS_PER_COMBO | Number of test files to run in parallel for each profile and browser combination during headless runs. Use a positive whole number. If omitted, ky asks for a number and uses 1 when left blank. | | NUM_COMBOS_IN_PARALLEL | Number of profile and browser combinations to run in parallel during headless runs. Use a positive whole number. If omitted, ky asks for a number and uses 1 when left blank. |

Setup Ky: npm run ky:setup

Whenever you update the version of ky or make changes to supporting project-specific commands or other non-test files, you should run ky:setup.

This will regenerate configuration files, typescript declarations, and other ky resources that keep your project working smoothly.

Setup and Start Ky Tests: npm run ky:dev

QA people and CI systems should start tests using npm run ky:start because that ensures that no files, dependencies, or files will be changed on run.

But, developers should run tests using npm run ky:dev because each time the tests are run, ky is automatically set up again, ensuring that ky files are up-to-date and running smoothly.

Customizing Ky

Adding globals

There are three types of globals: /cypress/globals/GlobalCredentials (secure values must go here), /cypress/globals/GlobalResources (videos, links, resources), and /cypress/globals/GlobalValues (everything else).

Controlling the Viewport

Each profile can set the viewport that tests run in via two optional variables:

| Variable | Description | | --- | --- | | viewport | A generic alias — desktop (a 4k monitor, the default), macbook, ipad, or iphone — or any Cypress viewport preset such as iphone-x, ipad-2, or macbook-16. Defaults to desktop. | | orientation | landscape or portrait. Defaults to landscape, except iphone viewports which default to portrait. |

The generic aliases map to specific devices: iphone → iphone-x, ipad → ipad-2, macbook → macbook-16, and desktop → a 4k monitor (3840×2160).

Ky applies the viewport automatically before each test.

const StageProfile = {
  baseURL: 'stage.example.harvard.edu',
  viewport: 'iphone',
  orientation: 'portrait',
};

export default StageProfile;

Writing Your Own Custom Commands

Custom commands are called using Ky (e.g. ky.myCustomCommand()), and you define them in the commands folder generated when you first setup Ky.

Create a new file when creating a custom command, and this file will take the following structure: (e.g. myCustomCommand.ts)

/// <reference types="cypress" />

/*----------------------------------------*/
/* ---------------- Type ---------------- */
/*----------------------------------------*/

declare global {
  namespace Cypress {
    interface Chainable {
      /**
       * My custom command
       * @author Your name here
       * @param any params
       * @returns what is returned
       */
      myCustomCommand(
        /* params here */
      ): Chainable</* your return type */>;
    }
  }
}

/*----------------------------------------*/
/* --------------- Command -------------- */
/*----------------------------------------*/

const myCustomCommand = () => {
  Cypress.Commands.add('myCustomCommand', (/* Function Params */) => {
    /* Function Body */
  });
};

/*----------------------------------------*/
/* --------------- Export --------------- */
/*----------------------------------------*/

export default myCustomCommand;

When you finish writing your command, run npm run ky:setup, which will let Ky initialize your command. You can now use your command in your tests!

All return types should be Chainable. For example, if your custom command returns a boolean, the return type should be Chainable<boolean>, and you would use it in a test like this:

ky.myCustomCommand().then((result) => {
  // result is typed as boolean here
});

Create your own return value?

Any time you don't return the value directly from another ky or Cypress command (for example, returning a primitive value or an object that you create), make sure to wrap it (ky.wrap()) so it can be properly chained. For example:

const myReturnValue = { hello: 'world' };

return ky.wrap(myReturnValue);

Adding a Custom Setup Node Events Script

If you want to add a custom setupNodeEvents script, create a /cypress/support/setupNodeEvents.ts module that exports a single default function of the following type:

((on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions) => Cypress.PluginConfigOptions | void)

Ky will automatically look for this file and add it to the configuration if it exists, so there's no need to import it or add it to the config manually. This is useful for adding custom functionality that happens outside the browser.