Skip to main content

Cypress

The @archibald/cypress package provides the Cypress integration for the archibald e2e command. See the Overview for the parts shared with Playwright.

Installation​

To install @archibald/cypress navigate to the root folder of your archibald project and execute

archibald add cypress

Usage​

Overview​

Similarily to the a standalone cypress installation the test specifications are located in the cypress/e2e folder. The tests utilize the page object model, the models are stored in cypress/pages.

Environments​

The environment configuration for the tests is stored in cypress/config. It's split into three parts, environment, features and selectors.

Executing Tests​

To execute the cypress tests simply run archibald e2e. This will open a cli, helping you to select the environment, headless mode, device mode, etc. It's also possible to provide the selections directly with the command with the following flags:

  • -h/--headless <true/false> Wether or not headless mode should be used
  • -b/--browser <chrome,electron,firefox> Which browser should be used
  • -m/--mode <desktop/mobile> Use desktop or mobile viewport
  • -e/--environment <environment name> Which environment should be used
  • -t/--tenant <tenant name> Which tenant should be used
  • -p/--platform <platform name> Which platform should be used
  • -l/--language <language name> Which language should be used

The command might look like this: archibald e2e -h false -b chrome -d desktop -e local -t netconomy.net -p shop -l en

Dev server​

archibald e2e starts the application for you — it boots archibald serve with the HMR/asset host pinned to localhost (so webpack chunks load from the same origin the tests navigate to), reuses an already-running server, and is a no-op in CI where the app is served externally. See the Overview. Don't keep a separate LAN-host archibald serve running while running e2e locally, or it will be reused.

Test user and custom commands​

cypress/support/commands.ts registers the custom commands used by the specs: cy.login(username, password), cy.fillForm(selector, data), cy.waitUntilSettled() and cy.waitForHydration(selector) (waits for the hydration island containing selector to finish hydrating before interacting — the Cypress counterpart of Playwright's waitForHydration; see the Playwright page).

The waitForHydration implementation ships in the @archibald/cypress package and is exported from the @archibald/cypress/support subpath (mirroring @archibald/playwright/support); commands.ts only wires it up as a cy command, so the command registration stays in your project and does not clash with the package.

Backend state is managed through getTestUser() (from support/helpers/methods), which returns the isolated test account together with operations to seed it — this replaces the former cy.resetUserAndCart command:

import { getTestUser } from 'support/helpers/methods';

beforeEach(() => {
    getTestUser().reset(); // clean account before each test
});

getTestUser() exposes email, password, reset(), addCart(products?), deleteCart(), addOrder(order?) and deleteOrder(orderId?); LoginPage.login() defaults to this account's credentials. See the Overview for the shared API and the mock endpoints it calls.

Tenant and Platform specific configuration​

Tenant and platform specific configuration is supported out of the box in the Cypress integration. All you need to do is to put the configuration, selectors and feature flags in the appropriate object in the configuration. The following example shows how it's done for selectors, it works the same for the configuraton and feature flags.

{
    "selectors": {
        "general": {
            "env": {
                "selectors": {
                }
            }
        },
        "tenant-a": {
            "env": {
                "selectors": {
                    "selectors_Usage": "Add only selectors which are available in 'tenant-a' here."
                }
            }
        },
        "tenant-b": {
            "env": {
                "selectors": {
                    "selectors_Usage": "Add only selectors which are available in 'tenant-b' here."
                }
            }
        },
        "platform-a": {
            "env": {
                "selectors": {
                    "selectors_Usage": "Add only selectors which are available on 'platform-a' here."
                }
            }
        },
        "platform-b": {
            "env": {
                "selectors": {
                    "selectors_Usage": "Add only selectors which are available on 'platform-b' here."
                }
            }
        }
    }
}

Tenant specific tests​

Specs are shadowed per tenant, the same way source files are: a spec at src/{platform}/e2e/tenant/{tenant}/specs/login.cy.ts replaces src/{platform}/e2e/specs/login.cy.ts for that tenant, and other tenants' specs stay out of the run. This needs cli.e2e.usePlatformSeparation: true (the flag that puts the suite under src/{platform} in the first place) — see Spec discovery and shadowing.

Prefer a feature flag with conditional statements when a tenant only differs in a step or two; reach for a shadowed spec when the flow genuinely diverges.

Platform specific tests​

Since Archibald Version 7.1 tests and page object are separated for each platform by default. They are located in src/{platform}/e2e when Cypress is the configured runner (cli.e2e.framework); if another runner owns the base folder, Cypress specs live in src/{platform}/e2e-cypress. See Where tests live for the full folder convention. If you started with your E2E tests in a previous version and want to switch to the platform separation you need to set cli.e2e.usePlatformSeparation to true and move the test and page objects files manually to the new location.

Gitlab CI​

When archibald add cypress was used to add Cypress to the project most configuration will have already been created automatically. This includes:

  • Cypress CI environment file
  • Archibald CI environment file
  • Gitlab CI pipeline

To fully enable the pipeline the docker build needs to be enabled in the archibald.json file and projects gitlab container registry needs to be added.

Example docker configuration​

"docker": {
            "active": true,
            "organization": "registry.gitlab.com/netconomy",
            "group": "cxfrontend",
            "project": "archibald"
        }

Further Documentation​

Cypress specific documentation can be found on the Cypress Homepage