Cypress: User-facing API

[skitterm]

What Changed

Simplified the user API as follows:

Before:

import { defineConfig } from 'cypress';
import { setupNetworkListener, onBeforeBrowserLaunch, saveArchives } from '@chromaui/test-archiver/cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        setupNetworkListener,
        saveArchives,
      });
      on('before:browser:launch', onBeforeBrowserLaunch);
    },
  },
});

After:

import { defineConfig } from 'cypress';
import { installPlugin } from '@chromaui/test-archiver/cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      installPlugin(on);
    },
  },
});

The user still needs to import our client-side beforeEach/afterEach hooks in their support file:

import '@chromaui/test-archiver/cypress/support';

The user will unfortunately also still have to pass
ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=x in front of their cypress run command still. Cypress doesn't allow for specifying a remote debugging port for Chrome, and electron doesn't pass the browser launch options (info like the CDP port), so we're stuck needing this ELECTRON_EXTRA_LAUNCH_ARGS env variable set by the user if they use Electron (which is the default for cypress run). Technically they don't need it if they are using Chrome/Chromium, but I think it's better to have all users add this then have a bunch of if-this-then-that's in our setup guide.

Note

Cypress lifecycle events can only be registered once. Because our installPlugin() registers an event listener on before:browser:launch event, if the user has such an event already, they will need to call installPlugin() first, and then register their before:browser:launch event, as follows:

import { defineConfig } from 'cypress';
import { installPlugin, onBeforeBrowserLaunch } from '@chromaui/test-archiver/cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      installPlugin(on);
      on('before:browser:launch', (browser, launchOptions) => {
           // register our event handler manually
           onBeforeBrowserLaunch(browser, launchOptions);
          doWhateverTheyDo(browser, launchOptions);
          return launchOptions;
     });
    },
  },
});

How to test

• Verify the automated Cypress tests still pass (here in PR checks)
• Locally, create a Cypress project and install this package version
• Change your cypress.config.ts file to match the new API
• Run the Cypress tests with yarn cypress run
• Verify the Cypress test run completes as expected
• Run yarn archive-storybook
• Verify that the storybook has the stories as before

• Author QA
• Reviewer QA

Change Type

• maintenance
• documentation
• patch
• minor
• major

📦 Published PR as canary version: 0.0.56--canary.55.8655fbb.1

✨ Test out this PR locally via:

npm install @chromaui/test-archiver@0.0.56--canary.55.8655fbb.1
# or 
yarn add @chromaui/test-archiver@0.0.56--canary.55.8655fbb.1

[tmeasday]

Love it @skitterm

[tevanoff]

Very nice!

[thafryer]

LGTM! Cypress is on a roll!

[thafryer]

🚀 PR was released in v0.0.56 🚀