@forsakringskassan/cypress-config

Sharable Cypress configuration building blocks for Försäkringskassan.

Install

npm install --save-dev @forsakringskassan/cypress-config

If you previously had these packages installed, they can be uninstalled:

npm rm \
  @forsakringskassan/cypress-axe \
  cypress-html-validate \
  mocha-multi-reporters

• Usage
• Commands
• Axe plugin
• docs-generator plugin
• HTML-Validate plugin

Usage

In cypress.config.ts, replace the vanilla defineConfig() helper from cypress with @forsakringskassan/cypress-config and pass in import.meta.dirname as the first parameter:

-import { defineConfig } from "cypress";
+import { defineConfig } from "@forsakringskassan/cypress-config";

-export default defineConfig({
+export default defineConfig(import.meta.dirname, {
   /* ... */
 });

It works the same but is preconfigured with new defaults.

[!TIP] The defineConfig() helper does not require the configuration object as the second parameter. Unless you are explicitly overwriting the default configuration it is recommended to call defineConfig() without it.

export default defineConfig(import.meta.dirname);

This ensures maximum compatibility with future releases.

A configuration function is available for usage in cypress/support/e2e.ts and/or cypress/support/component.ts:

import { configure } from "@forsakringskassan/cypress-config/support";

await configure({
    resetEmulatedMedia: true,
    afterEach: {
        htmlvalidate: true,
    },
});

[!NOTE]
The configure() function is expected to be called exactly once. If the call is omitted some functionality will not work as expected. Calling it multiple times is undefined behaviour.

• resetEmulatedMedia - When enabled, any emulated CSS media features will be reset between runs.
• afterEach - Enables features to automatically run after each test. See the various components for details.

For component tests a preconfigured mount function is available. It adds the following Vue plugins from @fkui/vue:

• FormatPlugin
• TestPlugin
• TranslationPlugin
• ValidationPlugin

Additionally, it also:

• Treats Vue warnings as errors.

To use, edit cypress/support/component.ts:

-import { mount } from "cypress/mount";
-import { configure } from "@forsakringskassan/cypress-config/support";
+import { configure, mount } from "@forsakringskassan/cypress-config/support";

 Cypress.Commands.add("mount", mount);

If you need further customization, wrap it in your own custom function:

Cypress.Commands.add("mount", (component, options = {}) => {
    /* modify options as needed */
    return mount(component, options);
});

For advanced usage, use the createMount() call to create the mount() function manually:

import { createMount } from "@forsakringskassan/cypress-config/support";

const mount = await createMount({/* options */});

Cypress.Commands.add("mount", mount);

Commands

This preset adds new custom commands:

forcedColors

• Syntax: cy.forcedColors(value)
• Parameters:
  • value: "active" | "none" - "active"" enables forced colors, "none" disables it.

Emulate CSS media feature forced-colors for testing High Contrast mode.

Unless resetEmulatedMedia is enabled, this modifies browser settings that persist until the next cy.forcedColors() call. It is independent from cy.prefersColorScheme(), e.g. if you want to use forced colors with dark mode you need to call both functions.

[!TIP] Enable resetEmulatedMedia in configure() to automatically reset emulated media features, including forced color mode, between tests.

prefersColorScheme

• Syntax: cy.prefersColorScheme(value)
• Parameters
  • value: "light" | "dark" | "none" - Sets the preferred color scheme or none to disable it (use system default).

Emulate CSS media feature prefers-color-scheme for testing light/dark mode themes.

Unless resetEmulatedMedia is enabled, this modifies browser settings that persist until the next cy.prefersColorScheme() call. It is independent from cy.forcedColors(), e.g. if you want to use forced colors with dark mode you need to call both functions.

[!TIP] Enable resetEmulatedMedia in configure() to automatically reset emulated media features, including the color scheme, between tests.

Axe plugin

A preconfigured Axe plugin (@forsakringskassan/cypress-axe) is exported as axePlugin:

import { defineConfig, axePlugin } from "@forsakringskassan/cypress-config";

export default defineConfig(import.meta.dirname, {
    component: {
        async setupNodeEvents(on, config) {
            config = await axePlugin(on, config);
            return config;
        },
    },
});

Automatic validation after each test cannot currently be disabled.

docs-generator plugin

A plugin to get all pages and examples generated by @forsakringskassan/docs-generator. This is typically only useful in E2E testing.

import {
    defineConfig,
    docsGeneratorPlugin,
} from "@forsakringskassan/cypress-config";
/
const docs = new Generator(import.meta.url, {});
const sourceFiles = [];

export default defineConfig(import.meta.dirname, {
    e2e: {
        async setupNodeEvents(on, config) {
            config = await docsGeneratorPlugin(on, config, docs, sourceFiles);
            return config;
        },
    },
});

The pages are retrieved using Cypress.expose("pages") which contains additional information:

const pages = Cypress.expose("pages") ?? [];
for (const page of pages) {
    const { path, examples } = page;
    /* ... */
}

See manifest documentation for details about what each page entry contains.

HTML-Validate plugin

A preconfigured HTML-validate plugin (cypress-html-validate) is exported as htmlValidatePlugin:

import {
    defineConfig,
    htmlValidatePlugin,
} from "@forsakringskassan/cypress-config";

export default defineConfig(import.meta.dirname, {
    component: {
        async setupNodeEvents(on, config) {
            config = await htmlValidatePlugin(on, config);
            return config;
        },
    },
});

To automatically run validation after each test configure it using the configuration function:

import { configure } from "@forsakringskassan/cypress-config/support";

await configure({
    resetEmulatedMedia: true,
    afterEach: {
        htmlvalidate: true,
    },
});