@trackunit/iris-app-e2e 1.11.25-alpha-27ad777c16e.0 → 1.11.28

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 1.11.28 (2026-06-10)
+
+### 🧱 Updated Dependencies
+
+- Updated react-vite-test-setup to 0.0.28
+
+## 1.11.27 (2026-06-10)
+
+### 🩹 Fixes
+
+- **e2e:** update deprecation message for iris-app-e2e ([e5cd2ad7539](https://github.com/Trackunit/manager/commit/e5cd2ad7539))
+
+### ❤️ Thank You
+
+- Mikkel Thorbjørn Andersen
+
+## 1.11.26 (2026-06-10)
+
+### 🧱 Updated Dependencies
+
+- Updated react-vite-test-setup to 0.0.27
+
+## 1.11.25 (2026-06-10)
+
+### 🧱 Updated Dependencies
+
+- Updated react-vite-test-setup to 0.0.26
+
 ## 1.11.24 (2026-06-10)
 
 ### 🧱 Updated Dependencies

package/MIGRATION.md

@@ -0,0 +1,207 @@
+# Migrating a Cypress E2E suite to Playwright
+
+`@trackunit/iris-app-e2e` (Cypress) is **deprecated** in favour of
+[`@trackunit/iris-app-playwright`](../iris-app-playwright/README.md) (Playwright).
+This guide shows how to move an existing project's Cypress suite to Playwright
+1:1. It is the recipe used to migrate the Trackunit-internal suites.
+
+> The shared Cypress plumbing stays in place during a grace period, so a project
+> can migrate at any time. Migrate the **project's own** Cypress files only; do
+> not remove the shared libraries, generator, or root `cypress` / `@nx/cypress`
+> dependencies.
+
+> [!NOTE]
+> **Import paths.** The examples below use the Trackunit-internal
+> `@trackunit/nx-playwright-support` wrapper, which is only resolvable inside this
+> monorepo. **External IrisX-app SDK consumers** should import the equivalent
+> `test` / `expect` / fixtures from the public **`@trackunit/iris-app-playwright`**
+> package instead (see its README); the fixture APIs (`login`, `irisApp`,
+> `configCat`, `getValidateFeatureFlags`, `LoginOptions`, …) are the same.
+
+## 1. Scaffold the Playwright config
+
+From the workspace root, run the generator for your project:
+
+```bash
+nx g @trackunit/iris-app-playwright:playwright-configuration <project-name>
+```
+
+This adds a `playwright.config.ts` wired to the shared preset. A minimal config
+looks like:
+
+```typescript
+import { createNxPreset, defaultPlaywrightConfig, setupPlugins } from "@trackunit/iris-app-playwright";
+import { format, resolveConfig } from "prettier";
+
+const nxPreset = createNxPreset(__filename);
+const config = defaultPlaywrightConfig({ configDir: __dirname, projectConfig: { testDir: "./playwright/tests" } });
+
+export default setupPlugins({ ...nxPreset, ...config }, { format, resolveConfig });
+```
+
+## 2. Create the `playwright/` directory
+
+```
+playwright/
+  tsconfig.json          # extends ../tsconfig.json, types: ["node"]
+  support/fixtures.ts     # re-exports test/describe/expect + a flexible login
+  tests/<name>.spec.ts    # the ported specs
+  fixtures/<name>.json     # auth fixtures moved from cypress/fixtures/
+```
+
+`playwright/tsconfig.json`:
+
+```json
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": { "types": ["node"], "sourceMap": false },
+  "include": ["**/*.ts", "**/*.js", "../playwright.config.ts", "./**/*.spec.ts", "./**/*.spec.tsx", "./**/*.d.ts"]
+}
+```
+
+`playwright/support/fixtures.ts` — a flexible `login` that mirrors `cy.login()`
+(bare = `auth.json`) and `cy.login("name")` (named fixture):
+
+```typescript
+import { describe, expect, type LoginOptions, test as baseTest } from "@trackunit/nx-playwright-support";
+import * as path from "path";
+
+const FIXTURES_DIR = path.resolve(__dirname, "..", "fixtures");
+
+export type LoginFn = (fixture?: string | LoginOptions) => Promise<void>;
+
+export const test = baseTest.extend<{ login: LoginFn }>({
+  login: async ({ login: baseLogin }, provide) => {
+    await provide(async (fixture?: string | LoginOptions) => {
+      if (typeof fixture === "string") {
+        await baseLogin({ fixturePath: path.join(FIXTURES_DIR, `${fixture}.json`) });
+      } else {
+        await baseLogin({ fixturePath: path.join(FIXTURES_DIR, "auth.json"), ...fixture });
+      }
+    });
+  },
+});
+
+export { describe, expect };
+```
+
+Suites that interact with the Iris app iframe should also override `irisApp` in
+this same `extend` block — see [Iframes](#iframes-cyenteririsapp) below.
+
+## 3. Port the specs (`*.cy.ts` -> `*.spec.ts`)
+
+Import `test` / `describe` / `expect` from your `support/fixtures`, and write
+async tests. Common command mappings:
+
+| Cypress | Playwright |
+| --- | --- |
+| `cy.login()` / `cy.login("name")` | `await login()` / `await login("name")` |
+| `cy.visit("/path")` | `await page.goto("/path")` |
+| `cy.getByTestId("x")` | `page.getByTestId("x")` |
+| `cy.get("[data-testid^=card]")` | `page.locator("[data-testid^=card]")` |
+| `.should("exist")` | `await expect(locator).toBeAttached()` |
+| `.should("be.visible")` | `await expect(locator).toBeVisible()` |
+| `.should("not.exist")` | `await expect(locator).toHaveCount(0)` |
+| `.should("have.length", n)` | `await expect(locator).toHaveCount(n)` |
+| `.should("have.length.greaterThan", 0)` | `await expect(locator.first()).toBeAttached()` |
+| `.should("contain"/"not.contain", t)` | `await expect(locator).toContainText(t)` / `.not.toContainText(t)` |
+| `.should("be.disabled")` | `await expect(locator).toBeDisabled()` |
+| `cy.get(input).clear().type(t)` | `await locator.fill(t)` (or `pressSequentially(t)` for autocompletes) |
+| `cy.get(input).type("{enter}")` | `await locator.press("Enter")` |
+| `cy.url().should("contain", "/x/")` | `await expect(page).toHaveURL(/\/x\//)` |
+| `cy.wait(1000)` | `await page.waitForTimeout(1000)` (avoid where possible) |
+
+### Network interception
+
+`cy.intercept({ url: "**/Op" }).as("op")` + `cy.wait("@op")` becomes a
+`page.waitForResponse(...)` **armed immediately before the action that triggers
+the request**:
+
+```typescript
+const op = page.waitForResponse(response => response.url().includes("Op"));
+await page.getByTestId("trigger").click();
+await op;
+```
+
+To modify a response (e.g. force a feature flag), use `page.route(...)`.
+
+### Iframes (`cy.enterIrisApp()`)
+
+`cy.enterIrisApp()` resolves `iframe[data-testid="app-iframe"]` and `.first()`.
+The base `irisApp` fixture returns a bare `page.frameLocator(...)`, so on pages
+that mount more than one `iframe[data-testid="app-iframe"]` Playwright strict mode
+throws. For parity, **also** override `irisApp` to add `.first()` in the same
+`support/fixtures.ts` `extend` block as `login`:
+
+```typescript
+import { type FrameLocator } from "@playwright/test";
+// ...inside the same baseTest.extend<{ login: LoginFn; irisApp: () => FrameLocator }>({ ... })
+  irisApp: async ({ page }, provide) => {
+    await provide(() => page.frameLocator('iframe[data-testid="app-iframe"]').first());
+  },
+```
+
+Then use the returned `FrameLocator`:
+
+```typescript
+const app = irisApp();
+await expect(app.getByTestId("page")).toBeAttached();
+```
+
+### Feature flags (`cy.getValidateFeatureFlags()` / `cy.configCat()`)
+
+```typescript
+test.beforeEach(async ({ getValidateFeatureFlags }) => {
+  getValidateFeatureFlags(); // arm BEFORE login navigates
+});
+
+test("...", async ({ page, login, configCat }) => {
+  await login();
+  const enabled = await configCat("my-flag");
+  // ...
+});
+```
+
+Note: `configCat` throws if the flag is missing in the `ValidateFeatureFlags`
+response. The shared Cypress `configCat` behaves the same (`find(...).state`), so
+await it directly; only wrap in `try/catch` if your Cypress original used
+optional chaining (`find(...)?.state`) to treat a missing flag as `false`.
+
+## 4. Wire up the project
+
+- `project.json`: switch the `e2e` / `e2e-ui` targets to the Playwright runner:
+
+  ```json
+  "e2e": {
+    "executor": "nx:run-commands",
+    "dependsOn": ["iris-app-playwright:ensure-playwright"],
+    "options": {
+      "command": "codeowner=<team> yarn playwright test --config=<path>/playwright.config.ts",
+      "forwardAllArgs": false
+    }
+  }
+  ```
+
+- `eslint.config.cjs`: repoint `parserOptions.project` at `./playwright/tsconfig.json`
+  (the shared e2e preset hardcodes `./cypress/tsconfig.json`, which no longer
+  exists) and disable the `testing-library/*` rules for `playwright/**` (they
+  false-positive on Playwright's `getByTestId` API).
+- `vitest.config.ts`: add `**/playwright/**` to `test.exclude`.
+- `tsconfig.json`: replace the `./cypress/tsconfig.json` reference with
+  `./playwright/tsconfig.json`.
+
+## 5. Validate, then remove the project's Cypress files
+
+```bash
+yarn playwright test --config=<path>/playwright.config.ts --list   # spec parity
+nx run <project>:tsc-validate
+nx run <project>:lint
+```
+
+Once green, delete the project's own `cypress.config.ts` and `cypress/`
+directory. **Do not** touch the shared plumbing.
+
+## 6. Ship it
+
+Open a PR for the owning team to review. Keep the conversion strictly 1:1 — same
+flows and assertions, preserve skips, add no new tests.

package/README.md

@@ -1,5 +1,21 @@
 # @trackunit/iris-app-e2e
 
+> [!WARNING]
+> **Deprecated — Cypress E2E is being replaced by Playwright.**
+>
+> `@trackunit/iris-app-e2e` (Cypress) is **deprecated** in favour of
+> [`@trackunit/iris-app-playwright`](../iris-app-playwright/README.md) (Playwright).
+> All Trackunit-internal suites have been migrated. The package **remains fully
+> functional during a grace period** so external IrisX-app developers can migrate
+> on their own schedule — nothing has been removed.
+>
+> - **New projects:** use `@trackunit/iris-app-playwright` and the
+>   `@trackunit/iris-app-playwright:playwright-configuration` generator.
+> - **Existing Cypress suites:** see the [migration guide](./MIGRATION.md).
+> - **Removal:** the shared Cypress plumbing will only be removed in a separate,
+>   future issue after the grace period ends. Watch this README and the external
+>   developer channels for the grace-period end date.
+
 A comprehensive E2E testing utilities library for Trackunit's Iris platform. This package provides reusable Cypress commands, setup utilities, and configuration helpers to streamline E2E testing for both internal and external developers.
 
 This library is exposed publicly for use in the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/iris-app-e2e",
-  "version": "1.11.25-alpha-27ad777c16e.0",
+  "version": "1.11.28",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "generators": "./generators.json",
@@ -37,9 +37,9 @@
   },
   "dependencies": {
     "@neuralegion/cypress-har-generator": "^5.17.0",
-    "@nx/cypress": "22.7.5",
-    "@nx/devkit": "22.7.5",
-    "@nx/vite": "22.7.5",
+    "@nx/cypress": "22.6.5",
+    "@nx/devkit": "22.6.5",
+    "@nx/vite": "22.6.5",
     "cypress-terminal-report": "7.0.3",
     "node-xlsx": "^0.23.0",
     "prettier": "^3.4.2",

package/src/index.d.ts

@@ -4,6 +4,13 @@
  *
  * For browser-only exports (commands, setup functions that use Cypress global),
  * import from "@trackunit/iris-app-e2e-support" instead.
+ *
+ * @deprecated Use `@trackunit/iris-app-playwright` (Playwright) instead. This
+ * Cypress library is kept functional during a grace period for external IrisX-app
+ * developers but is no longer the recommended path. New projects should use the
+ * `@trackunit/iris-app-playwright:playwright-configuration` generator; existing
+ * suites should follow the migration guide at
+ * libs/iris-app-sdk/iris-app-e2e/MIGRATION.md.
  */
 export * from "./plugins/createLogFile";
 export * from "./plugins/defaultPlugins";

package/src/index.js

@@ -8,6 +8,13 @@ const tslib_1 = require("tslib");
  *
  * For browser-only exports (commands, setup functions that use Cypress global),
  * import from "@trackunit/iris-app-e2e-support" instead.
+ *
+ * @deprecated Use `@trackunit/iris-app-playwright` (Playwright) instead. This
+ * Cypress library is kept functional during a grace period for external IrisX-app
+ * developers but is no longer the recommended path. New projects should use the
+ * `@trackunit/iris-app-playwright:playwright-configuration` generator; existing
+ * suites should follow the migration guide at
+ * libs/iris-app-sdk/iris-app-e2e/MIGRATION.md.
  */
 tslib_1.__exportStar(require("./plugins/createLogFile"), exports);
 tslib_1.__exportStar(require("./plugins/defaultPlugins"), exports);

package/src/support.d.ts

@@ -2,6 +2,11 @@
  * Browser-only exports for Cypress support files.
  * These modules depend on the Cypress global and must only be imported
  * in Cypress support files, NOT in cypress.config.ts or other Node.js contexts.
+ *
+ * @deprecated Use `@trackunit/iris-app-playwright` (Playwright) instead. This
+ * Cypress library is kept functional during a grace period for external IrisX-app
+ * developers but is no longer the recommended path. See the migration guide at
+ * libs/iris-app-sdk/iris-app-e2e/MIGRATION.md.
  */
 export * from "./commands/defaultCommands";
 export * from "./setup/defaultE2ESetup";

package/src/support.js

@@ -7,6 +7,11 @@ const tslib_1 = require("tslib");
  * Browser-only exports for Cypress support files.
  * These modules depend on the Cypress global and must only be imported
  * in Cypress support files, NOT in cypress.config.ts or other Node.js contexts.
+ *
+ * @deprecated Use `@trackunit/iris-app-playwright` (Playwright) instead. This
+ * Cypress library is kept functional during a grace period for external IrisX-app
+ * developers but is no longer the recommended path. See the migration guide at
+ * libs/iris-app-sdk/iris-app-e2e/MIGRATION.md.
  */
 tslib_1.__exportStar(require("./commands/defaultCommands"), exports);
 tslib_1.__exportStar(require("./setup/defaultE2ESetup"), exports);