testing

Testing Patterns for FAST

Use this guide when running or writing tests in the FAST monorepo. FAST uses Playwright for integration testing with a Vite dev server.

Running tests

Locally

First-time setup

After cloning and installing dependencies (npm ci), install Playwright browsers:

npx playwright install --with-deps

Commands

All commands are run from the monorepo root. Use -w to target a specific package.

Interactive / debug workflows

For FAST declarative tests in @microsoft/fast-element, these additional scripts are available:

Playwright UI mode (test:ui) starts a visual test runner where you can select and debug individual tests, view traces, and inspect DOM snapshots.

Declarative browser workflows resolve @microsoft/fast-element package imports directly to src and let Vite transpile TypeScript on demand. Vite does not type-check these modules; the package build remains responsible for type checking, while test:exports imports every emitted package export.

Through GitHub Actions

The repository uses several CI workflows to validate changes.

PR validation (ci-validate-pr.yml)

Runs on every pull request targeting main, releases/*, or features/* branches. Tests run on Ubuntu with Chromium only for fast feedback.

Key steps:

• Checks for change files (npm run checkchange)
• Biome lint/format check
• Builds affected packages (incremental with --since)
• Runs test:node and test:chromium for affected packages

Cross-platform validation (ci-validate-platforms.yml)

Runs on pushes to main, PRs targeting main, and on a weekly schedule. Tests run on Ubuntu, Windows, and macOS with Chromium, Firefox, and Safari.

This ensures cross-platform and cross-browser compatibility.

WebUI integration testing (ci-webui-integration.yml)

A dedicated workflow for validating FAST's integration with @microsoft/webui. This workflow runs on:

• Manual dispatch (workflow_dispatch)
• Pushes to webui/* branches

Note: This workflow does not run on regular pull requests. It is scoped to webui/* branches to test integration changes in isolation before they land on main.

The workflow builds all packages, installs Playwright Chromium, and runs:

npm run test:webui-integration -w @microsoft/fast-element

This builds each fixture with webui build --plugin=fast, renders the protocol with the fixture's state.json, and runs the same Playwright specs against the webui-rendered output.

To trigger WebUI integration tests for your changes:

1. Create a branch with the webui/ prefix (e.g., webui/my-integration-change).
2. Push the branch — the workflow runs automatically.
3. Alternatively, trigger the workflow manually from the Actions tab using workflow_dispatch.

Azure Pipelines (azure-pipelines-ci.yml)

The repository also has an Azure DevOps pipeline that runs on PRs to main. This pipeline runs in a 1ES-managed environment and includes SDL compliance checks in addition to building and testing.

Writing tests

FAST tests are Playwright integration tests that run against fixture pages served by Vite.

Test file conventions

• Test files use the *.spec.ts suffix (specifically *.pw.spec.ts for package src/ tests).
• Tests for developer-authored declarative markup and directives live in the matching test/declarative/fixtures/<category>/<feature>/<feature>.spec.ts fixture.
• Tests for implementation APIs and lifecycle behavior are co-located with their source as src/<feature>/<feature>.pw.spec.ts.

Writing declarative fixture tests

Fixture tests in @microsoft/fast-element/test/declarative/fixtures are the primary way to verify declarative template features. Each fixture is a self-contained test case with its own HTML, state, templates, and component definitions.

When changing declarative syntax, directive parsing, template generation, hydration behavior, or other user-authored template behavior, add or update a declarative fixture and exercise it in browser. Source-level parser tests may supplement narrow parsing edge cases, but they should not be the only coverage for syntax that users write in entry.html or templates.html. Use the local README files under packages/fast-element/test/declarative/fixtures/ and each fixture category to choose the right fixture type and follow category-specific examples.

For a complete guide on creating fixtures — including how to write entry.html, state.json, templates.html, main.ts, and spec files — see:

📄 Writing Fixtures

Quick example

import { expect, test } from "@playwright/test";

test.describe("my-feature", async () => {
    test("renders correctly", async ({ page }) => {
        await page.goto("/fixtures/bindings/my-feature/");

        const element = page.locator("my-element");
        await expect(element).toHaveText("Hello");
    });
});