Embedded UI Testing Reference

The Embedded UI uses a three-layer testing strategy: unit tests (Jest), integration tests (Jest with jsdom), and end-to-end tests (Playwright). This reference documents the test structure, how to run tests, and the CI pipeline configuration.

Test Layers

Each layer tests the system at a different level of depth. Unit tests check isolated logic quickly. Integration tests verify how the code behaves in a simulated browser environment. End-to-end tests run against a real browser and, optionally, a live server.

         ┌───────────────────┐
         │   E2E (Playwright)│  ~47 tests
         │   Full browser    │
         ├───────────────────┤
         │   Integration     │  ~14 tests
         │   Jest + jsdom    │
         ├───────────────────┤
         │   Unit Tests      │  ~50 tests
         │   Jest (mocked)   │
         └───────────────────┘

Unit Tests — Jest

Unit tests check individual functions and modules in isolation. External dependencies are replaced with test doubles (mocks) so tests run fast and do not require a running server.

Location: src/app/__tests__/

Running Unit Tests

Run these three test files together using the command below. The --testPathPatterns flag limits Jest to only the embed-related files.

cd packages/unqork-express
yarn test:jest --testPathPatterns "spa-embed|embed.integration|embed-loader"

E2E Tests — Playwright

End-to-end tests run in a real browser using Playwright. They verify behavior that unit tests cannot check, including whether a module renders visually, whether navigation works, and whether authentication flows complete correctly.

Location: e2e/tests/embedded/

Test Structure

Each spec file splits its tests into two sections to avoid requiring a live server for every test. Static tests use pre-built HTML and run in any environment. Live tests require a running Unqork server and are skipped locally if the server is unavailable.

Spec Files

The table below lists each spec file and how many static and live tests it contains.

Running E2E Tests

Use the commands below to run all E2E tests or to open the Playwright visual interface.

cd packages/unqork-express
yarn test:e2e        # All tests
yarn test:e2e:ui     # With Playwright UI

Server Availability Helper

Because some tests require a running server and others do not, the test suite uses a shared helper to decide what to do when the server is not available. The helper behaves differently depending on where the tests run.

Live server tests use handleServerUnavailable() from e2e/utils/helpers.ts:

• In CI (when the CI environment variable is set): returns an error so the failure is visible in the CI report.
• Locally: calls test.skip() so the test is skipped gracefully without failing the run.

CI Pipeline

The CI pipeline builds the Embedded UI, starts a local server, and runs the full Playwright suite. Tests that need a live server will fail visibly if the server does not start.

The E2E tests run in CI with the following setup:

1. Build unqork-express: yarn workspace unqork-express build:dev.
2. Start unqork-server with STATIC_DIR pointing to unqork-express/dist and NODE_ENV=local.
3. Wait for the server to respond on localhost:3000/embedded.js.
4. Run Playwright tests.
5. Live server tests fail visibly if the server did not start.

CI Server Requirements

The server startup in CI depends on several dependencies. If any are missing, the server may not start and live tests will fail.

The unqork-server requires dotenv, NODE_ENV, and a database connection. In CI, the server may fail to start if these dependencies are not available. Static HTML tests always pass regardless of server availability.