--- title: "Embedded UI Testing Reference" slug: "embedded-ui-testing-reference" tags: ["embedded-ui", "reference-guides"] status: "update" updated: 2026-10-13T18:19:20Z published: 2026-10-13T18:19:20Z canonical: "docs.unqork.io/embedded-ui-testing-reference" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # 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__/` | File | What It Tests | | --- | --- | | `spa-embed.test.js` | How templates are cached before Angular needs them, how Angular routing states are configured, how the navigation helper functions behave, and whether workflow states are set up correctly. | | `embed-loader.test.js` | The lifecycle of the `UnqorkCentauriElement` custom HTML element, including how it starts up, shuts down, and delegates mount/unmount calls, and whether config values pass through correctly. | | `embed.integration.test.js` | Whether the runtime correctly identifies the embed environment, whether embed-mode flags are set, whether the Shadow DOM is created and style-isolated properly, and whether modules and workflows mount as expected. | ### Running Unit Tests Run these three test files together using the command below. The `--testPathPatterns` flag limits Jest to only the embed-related files. ```bash 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. | Section | Approach | Server Required | | --- | --- | --- | | Static HTML Structure | Uses `page.setContent()` for fast DOM validation. | No | | Live Server Integration | Uses `page.goto()` against a running server. Gracefully skips if server is unavailable. | Yes | ### Spec Files The table below lists each spec file and how many static and live tests it contains. | File | Static Tests | Live Tests | Total | | --- | --- | --- | --- | | `authentication.spec.ts` | 3 | 3 | 6 | | `centauri-mount.spec.ts` | 4 | 10 | 14 | | `navigation-guards.spec.ts` | 2 | 1 | 3 | | `runtime-detection.spec.ts` | 6 | 4 | 10 | | `vega-mount.spec.ts` | 4 | 0 | 4 | | `workflow-mount.spec.ts` | 5 | 5 | 10 | ### Running E2E Tests Use the commands below to run all E2E tests or to open the Playwright visual interface. ```bash 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. --- **Changelog** | Date | Change | | --- | --- | | 2026-04-21 | Initial publication. | | 2026-06-15 | Updated headings to em dash format. | | 2026-06-11 | Editorial pass: removed HR dividers, added description paragraphs to all H2/H3 sections and code blocks, expanded unit test table descriptions for non-expert readers, updated internal link. | The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application. AngularJS is a JavaScript framework added to an HTML page with a