Skip to main content

Breaking: @trackunit/iris-app-playwright 0.3.1 requires awaiting irisApp()

@trackunit/iris-app-playwright 0.3.1 is a breaking release: irisApp() now returns a Promise<FrameLocator> in every environment. Because the package is still pre-1.0, the break shipped as a minor release, so a ^0.2.x range does not pick it up but any 0.3.x does.

Updated 2026-10-28: corrected the version. This entry previously said v1.0.0, which was never released; the change first shipped in 0.3.1.

Await it before using the app fixture:

// Before — no longer works
const app = irisApp();
await irisApp().getByTestId("asset-list").click();

// After
const app = await irisApp();
await app.getByTestId("asset-list").click();

// Or parenthesize a receiver chain
await (await irisApp()).getByTestId("asset-list").click();

Why this changed​

The stable promise contract allows tests that run against a feature branch to wait for the matching Iris App iframe before making page assertions. If that iframe never appears, the failure can be classified as host never became ready instead of surfacing as a misleading app assertion failure.

In normal external development, where NX_FEATURE_BRANCH_BASE_URL is not set, there is no additional wait: irisApp() resolves immediately while retaining the same promise-based API. The shared fixture also selects the first matching iframe, avoiding Playwright strict-mode failures when several matching iframes are present.

Migrate your tests​

The package includes the v0-3-0-await-iris-app migration. Update your Trackunit dependencies and run their migrations:

npx nx g @trackunit/migrations:migrate
npx nx g @trackunit/migrations:run-migrations

The migration:

  • awaits irisApp() calls inside async functions
  • changes local () => FrameLocator fixture types to () => Promise<FrameLocator>
  • leaves calls that are already awaited unchanged
  • reports synchronous locations as file:line so you can update them manually

For the complete update process, see Maintaining Your Application.