@trackunit/iris-app-playwright

A Playwright-based E2E testing utilities library for Trackunit's Iris platform. This package provides reusable fixtures, setup utilities, and configuration helpers, enabling teams to write end-to-end tests with Playwright.

This library is exposed publicly for use in the Trackunit Iris App SDK.

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Installation

npm install @trackunit/iris-app-playwright --save-dev

Peer Dependencies

npm install @playwright/test @nx/playwright --save-dev

Quickstart

1. Scaffold with the generator

nx generate @trackunit/iris-app-playwright:playwright-configuration --project my-app

This creates:

• playwright.config.ts wired to createNxPreset + defaultPlaywrightConfig + setupPlugins
• playwright/tsconfig.json
• playwright/support/fixtures.ts — re-exports test, expect, and describe
• playwright/fixtures/auth.json — fill in credentials
• playwright/tests/app.spec.ts — sample login spec
• e2e-pw and e2e-pw-ui targets in project.json

2. Fill in credentials

// playwright/fixtures/auth.json
{
  "username": "[email protected]",
  "password": "your-test-password"
}

3. Write a test

import { describe, expect, test } from "../support/fixtures";

describe("My Feature", () => {
  test("user can log in", async ({ page, login, irisApp }) => {
    await login();

    const app = irisApp();
    await expect(app.getByTestId("app-content")).toBeVisible();
  });
});

4. Run tests

# Against dev environment (headless)
yarn nx run my-app:e2e-pw --configuration=dev

# Interactive UI mode
yarn nx run my-app:e2e-pw-ui --configuration=local

Outside the devcontainer: Playwright browser binaries are not bundled. Run yarn playwright install once after yarn install to download them. The repo's devcontainer handles this automatically via ensure-playwright.sh.

Fixtures

All fixtures are available on the test object exported from @trackunit/iris-app-playwright/support.

login

Authenticates a user against the Trackunit platform.

login(options?: LoginOptions): Promise<void>

Reads credentials from playwright/fixtures/auth.json by default, or from PLAYWRIGHT_USERNAME / PLAYWRIGHT_PASSWORD environment variables. Navigates to /auth/manager-classic and waits for the host layout to be visible.

Per-worker storage state cache

The fixture maintains a worker-scoped, in-memory cache of authenticated storageState snapshots, keyed by (baseURL, username). Within a single Playwright worker:

1. The first login() call performs the full Okta flow (POST /api/v1/authn → sessionToken → /auth/manager-classic redirect) and captures the resulting cookies + localStorage.
2. Every subsequent login() call for the same (baseURL, username) hydrates those cookies/localStorage onto the current browser context and navigates straight to / — no Okta call.

This is what lets large suites run safely against shared environments (dev, stage) without tripping Okta's E0000047 rate limit, which fires once you fan out past a handful of parallel logins. Workers are independent processes, so each worker pays the slow path exactly once per identity.

You don't have to do anything to opt in — the cache is wired up automatically.

irisApp

Returns a FrameLocator for an Iris app iframe.

irisApp(options?: IrisAppOptions): FrameLocator

Defaults to iframe[data-testid="app-iframe"]. Pass testId to target a different iframe.

storybookPreview

Returns a FrameLocator for the Storybook preview iframe.

storybookPreview(options?: StorybookPreviewOptions): FrameLocator

Defaults to iframe[id="storybook-preview-iframe"]. Pass iframeId to target a different preview iframe.

getValidateFeatureFlags

Installs a response interceptor that captures the ValidateFeatureFlags GraphQL response for the current page.

getValidateFeatureFlags(): void

Call this before navigating to ensure the response is captured from the first load.

configCat

Returns the boolean state of a ConfigCat feature flag.

configCat(flag: string): Promise<boolean>

Waits for the ValidateFeatureFlags response if it hasn't been captured yet.

switchToLocalDevMode

Navigates to the Iris SDK portal and enables the local dev mode toggle.

switchToLocalDevMode(): Promise<void>

HAR recording and logs

Failed tests automatically:

• Write a redacted JSON log file to <outputDir>/logs/<testTitle>_failed_<retry>.log
• Retain a HAR file at <outputDir>/hars/<testTitle>_failed_<retry>.har

Passing tests have their HAR file deleted. The log file is never written for passing tests.

Both the logs and HAR directories derive from the resolved outputDir, so every artifact for a run stays inside the one Playwright output tree (under the per-executor partition on CI).

Sensitive values (password, sessionToken, accessToken, refreshToken, idToken, authorization) are automatically redacted from log output with ***.

Tuning parallelism

defaultPlaywrightConfig accepts a behaviorConfig object with two parallelism knobs:

defaultPlaywrightConfig({
  configDir: __dirname,
  behaviorConfig: {
    workers: 2,          // number or "50%" (Playwright shorthand)
    fullyParallel: false,
  },
});

workers

Resolution order:

1. If behaviorConfig.workers is set, it always wins.
2. Otherwise, when BASE_URL (or NX_FEATURE_BRANCH_BASE_URL) points at a shared environment — i.e. anything other than localhost, 127.0.0.1, 0.0.0.0, ::1, or a *.local / *.localhost host — workers is automatically capped at 2. This pairs with the login fixture's per-worker storageState cache: the cache collapses repeat logins within a worker, the cap limits the initial parallel login fan-out at suite startup, and together they keep Okta's /api/v1/authn comfortably under the E0000047 rate limit.
3. Otherwise (BASE_URL unset or local), Playwright's own default applies — typically Math.ceil(os.cpus().length / 2) locally and 1 on CI.

Pass an explicit workers value to override the auto-cap, e.g. when running against a non-Okta environment.

fullyParallel

Defaults to Playwright's behaviour (undefined, project-level setting wins). Set explicitly to opt files in or out of intra-file parallelism.

Codeowner suffix

Set the codeowner environment variable to append a [team-name] suffix to all describe titles in the test report:

codeowner=team-gluon-fe yarn nx run my-app:e2e-pw --configuration=dev

Use the describe wrapper exported from @trackunit/iris-app-playwright/support (not Playwright's built-in test.describe) to get this behaviour.

Cypress to Playwright parity table

| Cypress API | Playwright equivalent | |---|---| | cy.login("auth") | await login() | | cy.enterIrisApp() | irisApp() returns FrameLocator | | cy.enterStorybookPreview() | storybookPreview() returns FrameLocator | | cy.getValidateFeatureFlags() | getValidateFeatureFlags() | | cy.configCat("flag") | await configCat("flag") | | cy.switchToLocalDevMode() | await switchToLocalDevMode() | | cy.getByTestId("id") | page.getByTestId("id") (built-in Playwright) | | setupE2E() | Handled by setupPlugins in playwright.config.ts | | setupHarRecording() | Built in to LogsReporter via setupPlugins | | describe("...", fn) | describe("...", fn) from @trackunit/iris-app-playwright/support | | defaultCypressConfig() | defaultPlaywrightConfig() | | setupPlugins(on, config, ...) | setupPlugins(config, formatter) | | createNxPreset(__filename) | createNxPreset(__filename) |

Development

This library is developed by Trackunit employees. See INTERNAL.md for maintainer notes.

Trackunit

This package was developed by Trackunit ApS. Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.