From cf5f9a7c330093664020812414b092ffe1a5c5f9 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:30:11 -0700 Subject: [PATCH 1/3] docs: clarify declarative fixture test guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/testing/SKILL.md | 9 +++++++++ .../test/declarative/fixtures/WRITING_FIXTURES.md | 15 +++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/.github/skills/testing/SKILL.md b/.github/skills/testing/SKILL.md index 4a30a1dd58f..b6f3bfa476a 100644 --- a/.github/skills/testing/SKILL.md +++ b/.github/skills/testing/SKILL.md @@ -109,6 +109,15 @@ FAST tests are [Playwright](https://playwright.dev/) integration tests that run 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`. For directive +syntax, start with the fixtures under +`packages/fast-element/test/declarative/fixtures/directives/`; for example, +`directives/children` covers `f-children`. + 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](../../../packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md)** diff --git a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md index fa09ce098da..76a7f99f387 100644 --- a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md +++ b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md @@ -50,6 +50,21 @@ Fixtures are auto-discovered by scanning category directories for subdirectories --- +## When to add or update a fixture + +Use fixtures for changes to declarative syntax, directive parsing, template +generation, hydration behavior, or other behavior that users express in +`entry.html` or `templates.html`. Fixture coverage runs the generated template +in a browser and catches integration issues that parser-only tests can miss. + +Source-level parser tests may still be useful for very narrow edge cases, but +they should supplement fixture coverage rather than replace it. For directive +syntax changes, add or update the matching fixture under `directives/` (for +example, `directives/children` for `f-children`) and assert the behavior from +the fixture's Playwright spec. + +--- + ## fast-build.config.json Each fixture must include a `fast-build.config.json` file that tells the `@microsoft/fast-build` CLI where to find the fixture's source files and how to build them. The build script passes `--config=` to the CLI for each fixture. From bbf482e5909751b55d341897b507b18000bd4746 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:36:15 -0700 Subject: [PATCH 2/3] docs: avoid wrapped fixture guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/testing/SKILL.md | 9 +-------- .../test/declarative/fixtures/WRITING_FIXTURES.md | 13 +++---------- 2 files changed, 4 insertions(+), 18 deletions(-) diff --git a/.github/skills/testing/SKILL.md b/.github/skills/testing/SKILL.md index b6f3bfa476a..cadbfc14bcc 100644 --- a/.github/skills/testing/SKILL.md +++ b/.github/skills/testing/SKILL.md @@ -109,14 +109,7 @@ FAST tests are [Playwright](https://playwright.dev/) integration tests that run 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`. For directive -syntax, start with the fixtures under -`packages/fast-element/test/declarative/fixtures/directives/`; for example, -`directives/children` covers `f-children`. +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`. For directive syntax, start with the fixtures under `packages/fast-element/test/declarative/fixtures/directives/`; for example, `directives/children` covers `f-children`. For a complete guide on creating fixtures — including how to write `entry.html`, `state.json`, `templates.html`, `main.ts`, and spec files — see: diff --git a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md index 76a7f99f387..ca65e157218 100644 --- a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md +++ b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md @@ -52,16 +52,9 @@ Fixtures are auto-discovered by scanning category directories for subdirectories ## When to add or update a fixture -Use fixtures for changes to declarative syntax, directive parsing, template -generation, hydration behavior, or other behavior that users express in -`entry.html` or `templates.html`. Fixture coverage runs the generated template -in a browser and catches integration issues that parser-only tests can miss. - -Source-level parser tests may still be useful for very narrow edge cases, but -they should supplement fixture coverage rather than replace it. For directive -syntax changes, add or update the matching fixture under `directives/` (for -example, `directives/children` for `f-children`) and assert the behavior from -the fixture's Playwright spec. +Use fixtures for changes to declarative syntax, directive parsing, template generation, hydration behavior, or other behavior that users express in `entry.html` or `templates.html`. Fixture coverage runs the generated template in a browser and catches integration issues that parser-only tests can miss. + +Source-level parser tests may still be useful for very narrow edge cases, but they should supplement fixture coverage rather than replace it. For directive syntax changes, add or update the matching fixture under `directives/` (for example, `directives/children` for `f-children`) and assert the behavior from the fixture's Playwright spec. --- From e13d62ad0e74d61149ad3392774ea7265a1931a6 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:38:37 -0700 Subject: [PATCH 3/3] docs: reference fixture README guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/testing/SKILL.md | 2 +- ...-fast-element-1a06cb78-b971-48a9-8c9c-e3ff31fa0383.json | 7 +++++++ .../test/declarative/fixtures/WRITING_FIXTURES.md | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 change/@microsoft-fast-element-1a06cb78-b971-48a9-8c9c-e3ff31fa0383.json diff --git a/.github/skills/testing/SKILL.md b/.github/skills/testing/SKILL.md index cadbfc14bcc..4e145f2956a 100644 --- a/.github/skills/testing/SKILL.md +++ b/.github/skills/testing/SKILL.md @@ -109,7 +109,7 @@ FAST tests are [Playwright](https://playwright.dev/) integration tests that run 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`. For directive syntax, start with the fixtures under `packages/fast-element/test/declarative/fixtures/directives/`; for example, `directives/children` covers `f-children`. +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: diff --git a/change/@microsoft-fast-element-1a06cb78-b971-48a9-8c9c-e3ff31fa0383.json b/change/@microsoft-fast-element-1a06cb78-b971-48a9-8c9c-e3ff31fa0383.json new file mode 100644 index 00000000000..e3b922630d8 --- /dev/null +++ b/change/@microsoft-fast-element-1a06cb78-b971-48a9-8c9c-e3ff31fa0383.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Document declarative fixture testing guidance.", + "packageName": "@microsoft/fast-element", + "email": "7559015+janechu@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md index ca65e157218..92aaa4a0dbc 100644 --- a/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md +++ b/packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md @@ -54,7 +54,7 @@ Fixtures are auto-discovered by scanning category directories for subdirectories Use fixtures for changes to declarative syntax, directive parsing, template generation, hydration behavior, or other behavior that users express in `entry.html` or `templates.html`. Fixture coverage runs the generated template in a browser and catches integration issues that parser-only tests can miss. -Source-level parser tests may still be useful for very narrow edge cases, but they should supplement fixture coverage rather than replace it. For directive syntax changes, add or update the matching fixture under `directives/` (for example, `directives/children` for `f-children`) and assert the behavior from the fixture's Playwright spec. +Source-level parser tests may still be useful for very narrow edge cases, but they should supplement fixture coverage rather than replace it. Use the local README files in this directory and each fixture category to choose the right fixture type, then add or update the matching fixture and assert the behavior from the fixture's Playwright spec. ---