@trackunit/iris-app-playwright 0.1.1

package/README.md

@@ -0,0 +1,230 @@
+# @trackunit/iris-app-playwright
+
+A Playwright-based E2E testing utilities library for Trackunit's Iris platform — the Playwright equivalent of `@trackunit/iris-app-e2e`. This package provides reusable fixtures, setup utilities, and configuration helpers that mirror the Cypress support library's API, enabling teams to adopt Playwright while preserving familiar patterns.
+
+This library is exposed publicly for use in the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app).
+
+For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
+
+> **See also:** [`@trackunit/iris-app-e2e`](../iris-app-e2e/README.md) — the equivalent Cypress library. Both are supported; teams opt in to Playwright on their own schedule.
+
+## Installation
+
+```bash
+npm install @trackunit/iris-app-playwright --save-dev
+```
+
+## Peer Dependencies
+
+```bash
+npm install @playwright/test @nx/playwright --save-dev
+```
+
+## Quickstart
+
+### 1. Scaffold with the generator
+
+```bash
+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
+
+```json
+// playwright/fixtures/auth.json
+{
+  "username": "your-test-user@example.com",
+  "password": "your-test-password"
+}
+```
+
+### 3. Write a test
+
+```typescript
+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
+
+```bash
+# 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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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:
+
+```typescript
+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:
+
+```bash
+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](./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.
+
+![The Trackunit logo](https://trackunit.com/wp-content/uploads/2022/03/top-logo.svg)

package/generators.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "iris-app-playwright",
+  "version": "1.0.0",
+  "generators": {
+    "playwright-configuration": {
+      "factory": "./src/generators/playwright-configuration/generator#playwrightConfigurationGenerator",
+      "schema": "./src/generators/playwright-configuration/schema.json",
+      "description": "Playwright E2E configuration setup for Iris app projects"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@trackunit/iris-app-playwright",
+  "version": "0.1.1",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "generators": "./generators.json",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "import": "./src/index.js"
+    },
+    "./support": {
+      "types": "./src/support.d.ts",
+      "require": "./src/support.js",
+      "import": "./src/support.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "support": [
+        "./src/support.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@nx/devkit": "22.6.5",
+    "@nx/playwright": "22.6.5",
+    "jszip": "^3.10.1",
+    "prettier": "^3.4.2",
+    "tslib": "^2.6.2"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.60.0"
+  },
+  "type": "commonjs"
+}

package/src/fixtures/baseTest.d.ts

@@ -0,0 +1,9 @@
+import { expect } from "@playwright/test";
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    _harRecording: void;
+} & import("./login.fixture").TrackunitBaseFixtures & import("./irisApp.fixture").IrisAppFixtures & import("./featureFlags.fixture").FeatureFlagFixtures & import("./localDevMode.fixture").LocalDevModeFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & import("./login.fixture").LoginCacheFixtures>;
+export { expect };
+export type { FeatureFlag, FeatureFlagFixtures } from "./featureFlags.fixture";
+export type { IrisAppFixtures, IrisAppOptions, StorybookPreviewOptions } from "./irisApp.fixture";
+export type { LocalDevModeFixtures } from "./localDevMode.fixture";
+export type { AuthCredentials, LoginOptions, TrackunitBaseFixtures } from "./login.fixture";

package/src/fixtures/baseTest.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expect = exports.test = void 0;
+const test_1 = require("@playwright/test");
+Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
+const featureFlags_fixture_1 = require("./featureFlags.fixture");
+const harRecording_fixture_1 = require("./harRecording.fixture");
+const irisApp_fixture_1 = require("./irisApp.fixture");
+const localDevMode_fixture_1 = require("./localDevMode.fixture");
+const login_fixture_1 = require("./login.fixture");
+exports.test = (0, test_1.mergeTests)(harRecording_fixture_1.test, login_fixture_1.test, irisApp_fixture_1.test, featureFlags_fixture_1.test, localDevMode_fixture_1.test);
+//# sourceMappingURL=baseTest.js.map

package/src/fixtures/describe.d.ts

@@ -0,0 +1,11 @@
+type DescribeCallback = () => void;
+type DescribeFn = (title: string, callback: DescribeCallback) => void;
+/**
+ * Wrapped `describe` that appends `[codeowner]` to the suite title when the
+ * `codeowner` environment variable is set. Drop-in replacement for `test.describe`.
+ */
+export declare const describe: DescribeFn & {
+    only: DescribeFn;
+    skip: DescribeFn;
+};
+export {};

package/src/fixtures/describe.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describe = void 0;
+const test_1 = require("@playwright/test");
+const addOwnerToTitle = (title) => {
+    const codeowner = process.env.codeowner;
+    return codeowner ? `${title} [${codeowner}]` : title;
+};
+/**
+ * Wrapped `describe` that appends `[codeowner]` to the suite title when the
+ * `codeowner` environment variable is set. Drop-in replacement for `test.describe`.
+ */
+exports.describe = Object.assign((title, callback) => {
+    test_1.test.describe(addOwnerToTitle(title), callback);
+}, {
+    only: (title, callback) => {
+        test_1.test.describe.only(addOwnerToTitle(title), callback);
+    },
+    skip: (title, callback) => {
+        test_1.test.describe.skip(addOwnerToTitle(title), callback);
+    },
+});
+//# sourceMappingURL=describe.js.map

package/src/fixtures/featureFlags.fixture.d.ts

@@ -0,0 +1,19 @@
+export interface FeatureFlag {
+    key: string;
+    state: boolean;
+}
+export interface FeatureFlagFixtures {
+    /**
+     * Call before the navigation that triggers `ValidateFeatureFlags`, `UserPermissions`,
+     * and `ActiveSubscription` requests to ensure the responses are captured for `configCat`.
+     */
+    getValidateFeatureFlags: () => void;
+    /**
+     * Returns the state of a ConfigCat feature flag from the captured `ValidateFeatureFlags` response.
+     * Waits for the response if not yet captured.
+     *
+     * @param flag - The feature flag key to look up
+     */
+    configCat: (flag: string) => Promise<boolean>;
+}
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & FeatureFlagFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/src/fixtures/featureFlags.fixture.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+const test_1 = require("@playwright/test");
+const featureFlagsCache = new WeakMap();
+const featureFlagsInFlight = new WeakMap();
+const listenerInstalled = new WeakSet();
+const extractFlags = async (response) => {
+    const body = await response.json();
+    const flags = body?.data?.featureFlags;
+    return Array.isArray(flags) ? flags : undefined;
+};
+// Tracks the in-flight extraction promise per page so `configCat` can await it
+// instead of falling through to `page.waitForResponse(...)`, which would wait
+// for the *next* matching response and hang when the original already happened.
+const trackExtraction = (page, response) => {
+    const promise = extractFlags(response)
+        .then(flags => {
+        if (flags !== undefined) {
+            featureFlagsCache.set(page, flags);
+        }
+        return flags;
+    })
+        .finally(() => {
+        if (featureFlagsInFlight.get(page) === promise) {
+            featureFlagsInFlight.delete(page);
+        }
+    });
+    featureFlagsInFlight.set(page, promise);
+    return promise;
+};
+const installFlagListener = (page) => {
+    if (listenerInstalled.has(page)) {
+        return;
+    }
+    listenerInstalled.add(page);
+    page.on("response", response => {
+        if (response.url().includes("ValidateFeatureFlags") && response.ok()) {
+            void trackExtraction(page, response);
+        }
+    });
+};
+exports.test = test_1.test.extend({
+    getValidateFeatureFlags: async ({ page }, provide) => {
+        await provide(() => {
+            installFlagListener(page);
+        });
+    },
+    configCat: async ({ page }, provide) => {
+        await provide(async (flag) => {
+            if (!featureFlagsCache.has(page)) {
+                installFlagListener(page);
+                // If the listener already saw the response, an extraction is in flight —
+                // await it before deciding to wait for another network response.
+                const inFlight = featureFlagsInFlight.get(page);
+                if (inFlight !== undefined) {
+                    await inFlight;
+                }
+                if (!featureFlagsCache.has(page)) {
+                    const response = await page.waitForResponse(r => r.url().includes("ValidateFeatureFlags") && r.ok(), { timeout: 30000 });
+                    const parsedFlags = await extractFlags(response);
+                    if (parsedFlags !== undefined) {
+                        featureFlagsCache.set(page, parsedFlags);
+                    }
+                }
+            }
+            const cachedFlags = featureFlagsCache.get(page);
+            const found = cachedFlags?.find(ff => ff.key === flag);
+            if (found === undefined) {
+                throw new Error(`Feature flag '${flag}' not found in ValidateFeatureFlags response`);
+            }
+            return found.state;
+        });
+    },
+});
+//# sourceMappingURL=featureFlags.fixture.js.map

package/src/fixtures/harRecording.fixture.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adds Playwright HAR recording without replacing the built-in `context` fixture.
+ *
+ * `contextOptions` is merged into the default `browser.newContext()` call by Playwright's
+ * own `context` fixture, so trace/video/screenshot retention configured via `use` still works.
+ * `_harRecording` is an auto-fixture that depends on `context` so its teardown runs after the
+ * context closes — that's when Playwright flushes the HAR file to disk, which is when we
+ * can attach it as `har` for `LogsReporter` to retain (on failure) or delete (on pass).
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    _harRecording: void;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/src/fixtures/harRecording.fixture.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+const test_1 = require("@playwright/test");
+const fs_1 = require("fs");
+const HAR_FILENAME = "test.har";
+/**
+ * Adds Playwright HAR recording without replacing the built-in `context` fixture.
+ *
+ * `contextOptions` is merged into the default `browser.newContext()` call by Playwright's
+ * own `context` fixture, so trace/video/screenshot retention configured via `use` still works.
+ * `_harRecording` is an auto-fixture that depends on `context` so its teardown runs after the
+ * context closes — that's when Playwright flushes the HAR file to disk, which is when we
+ * can attach it as `har` for `LogsReporter` to retain (on failure) or delete (on pass).
+ */
+exports.test = test_1.test.extend({
+    contextOptions: async ({ contextOptions }, provide, testInfo) => {
+        const harPath = testInfo.outputPath(HAR_FILENAME);
+        await provide({
+            ...contextOptions,
+            recordHar: { path: harPath, mode: "minimal" },
+        });
+    },
+    _harRecording: [
+        async ({ context: _context }, provide, testInfo) => {
+            await provide();
+            const harPath = testInfo.outputPath(HAR_FILENAME);
+            if ((0, fs_1.existsSync)(harPath)) {
+                await testInfo.attach("har", { path: harPath });
+            }
+        },
+        { auto: true },
+    ],
+});
+//# sourceMappingURL=harRecording.fixture.js.map

package/src/fixtures/hydrateStorageState.d.ts

@@ -0,0 +1,36 @@
+import type { BrowserContext } from "@playwright/test";
+/**
+ * Subset of Playwright's `StorageState` we persist between tests within the
+ * same worker. We model it explicitly rather than re-exporting
+ * `Awaited<ReturnType<BrowserContext['storageState']>>` so the cache
+ * contract is greppable from spec files and Playwright API churn cannot
+ * silently widen what we're persisting.
+ */
+export interface CachedStorageState {
+    cookies: Parameters<BrowserContext["addCookies"]>[0];
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+export type StorageStateHydrator = Pick<BrowserContext, "addCookies" | "addInitScript">;
+/**
+ * Restores cookies and localStorage from a cached `storageState` snapshot
+ * into the supplied browser context.
+ *
+ * Cookies go through `context.addCookies` (synchronous from the page's POV
+ * because they're set before any navigation). LocalStorage requires an
+ * `addInitScript` because it can only be written by JS executing on the
+ * matching origin — Playwright runs the init script in every new document,
+ * and we gate it by `window.location.origin` so we don't smuggle localStorage
+ * onto unrelated origins (e.g. about:blank, OAuth IdP domains, or iframes
+ * pointing at iris-app subdomains).
+ *
+ * Wrapping each `setItem` in try/catch protects against contexts where
+ * localStorage is unavailable (private browsing modes, sandboxed iframes,
+ * etc.) — we never want hydration to crash the page load.
+ */
+export declare const hydrateStorageState: (context: StorageStateHydrator, state: CachedStorageState) => Promise<void>;

package/src/fixtures/hydrateStorageState.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hydrateStorageState = void 0;
+/**
+ * Restores cookies and localStorage from a cached `storageState` snapshot
+ * into the supplied browser context.
+ *
+ * Cookies go through `context.addCookies` (synchronous from the page's POV
+ * because they're set before any navigation). LocalStorage requires an
+ * `addInitScript` because it can only be written by JS executing on the
+ * matching origin — Playwright runs the init script in every new document,
+ * and we gate it by `window.location.origin` so we don't smuggle localStorage
+ * onto unrelated origins (e.g. about:blank, OAuth IdP domains, or iframes
+ * pointing at iris-app subdomains).
+ *
+ * Wrapping each `setItem` in try/catch protects against contexts where
+ * localStorage is unavailable (private browsing modes, sandboxed iframes,
+ * etc.) — we never want hydration to crash the page load.
+ */
+const hydrateStorageState = async (context, state) => {
+    if (state.cookies.length > 0) {
+        await context.addCookies(state.cookies);
+    }
+    if (state.origins.length === 0) {
+        return;
+    }
+    await context.addInitScript((origins) => {
+        const match = origins.find(entry => entry.origin === window.location.origin);
+        if (match === undefined) {
+            return;
+        }
+        for (const { name, value } of match.localStorage) {
+            try {
+                window.localStorage.setItem(name, value);
+            }
+            catch {
+                /* localStorage may be unavailable (sandboxed iframe, private mode) — skip silently. */
+            }
+        }
+    }, state.origins);
+};
+exports.hydrateStorageState = hydrateStorageState;
+//# sourceMappingURL=hydrateStorageState.js.map

package/src/fixtures/irisApp.fixture.d.ts

@@ -0,0 +1,15 @@
+import { type FrameLocator } from "@playwright/test";
+export interface IrisAppOptions {
+    testId?: string;
+}
+export interface StorybookPreviewOptions {
+    /** Storybook preview iframe element id. Defaults to `storybook-preview-iframe`. */
+    iframeId?: string;
+}
+export interface IrisAppFixtures {
+    /** Returns a FrameLocator for the iris app iframe. Defaults to `data-testid="app-iframe"`. */
+    irisApp: (options?: IrisAppOptions) => FrameLocator;
+    /** Returns a FrameLocator for the Storybook preview iframe. Defaults to `id="storybook-preview-iframe"`. */
+    storybookPreview: (options?: StorybookPreviewOptions) => FrameLocator;
+}
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & IrisAppFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/src/fixtures/irisApp.fixture.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+const test_1 = require("@playwright/test");
+exports.test = test_1.test.extend({
+    irisApp: async ({ page }, provide) => {
+        await provide((options) => page.frameLocator(`iframe[data-testid="${options?.testId ?? "app-iframe"}"]`));
+    },
+    storybookPreview: async ({ page }, provide) => {
+        await provide((options) => page.frameLocator(`iframe[id="${options?.iframeId ?? "storybook-preview-iframe"}"]`));
+    },
+});
+//# sourceMappingURL=irisApp.fixture.js.map

package/src/fixtures/localDevMode.fixture.d.ts

@@ -0,0 +1,5 @@
+export interface LocalDevModeFixtures {
+    /** Navigates to the developer portal and toggles local dev mode on if not already enabled. */
+    switchToLocalDevMode: () => Promise<void>;
+}
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & LocalDevModeFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/src/fixtures/localDevMode.fixture.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+const test_1 = require("@playwright/test");
+exports.test = test_1.test.extend({
+    switchToLocalDevMode: async ({ page }, provide) => {
+        await provide(async () => {
+            await page.getByTestId("developerPortalNav").click();
+            await page.waitForURL(url => url.toString().includes("/iris-sdk-portal"), { timeout: 15000 });
+            const toggle = page.getByTestId("localDevModeSwitch-input");
+            if (!(await toggle.isChecked())) {
+                await page.getByTestId("localDevModeSwitch-thumb").click();
+            }
+        });
+    },
+});
+//# sourceMappingURL=localDevMode.fixture.js.map

package/src/fixtures/login.fixture.d.ts

@@ -0,0 +1,24 @@
+import { type CachedStorageState } from "./hydrateStorageState";
+import { type AuthCredentials, type ResolveCredentialsOptions } from "./resolveCredentials";
+export type { AuthCredentials };
+export type LoginOptions = ResolveCredentialsOptions;
+export interface TrackunitBaseFixtures {
+    login: (options?: LoginOptions) => Promise<void>;
+}
+/**
+ * Worker-scoped, in-memory cache of authenticated `storageState` snapshots,
+ * keyed by `(baseURL, username)`. Implementation detail of the `login`
+ * fixture — exposed on the fixtures object so Playwright can manage its
+ * lifecycle, but prefixed with `_` to signal "don't touch from tests".
+ */
+export interface LoginCacheFixtures {
+    _loginCache: Map<string, CachedStorageState>;
+}
+/**
+ * Each worker is its own Node process, so a `Map` is sufficient — no
+ * cross-worker sharing concerns, no disk I/O, no cleanup needed. The cache
+ * dies with the worker, which is the desired behaviour: a fresh `nx run`
+ * always starts with empty caches.
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TrackunitBaseFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & LoginCacheFixtures>;
+export { expect } from "@playwright/test";