@sun-asterisk/sungen 2.4.6 → 2.5.0

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -40,7 +40,9 @@ After each command completes, use `AskUserQuestion` to present the next actions
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
 ├── selectors/<screen>.yaml        # Element locators (generated during run-test)
-├── test-data/<screen>.yaml        # Test data variables
+├── test-data/<screen>.yaml        # Test data variables (loaded at runtime)
+├── test-data/<screen>.staging.yaml    # Environment override (optional)
+├── test-data/<screen>.production.yaml # Environment override (optional)
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
@@ -49,12 +51,19 @@ qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen:deli
 qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ```
 
+## Test Data
+
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+
+**Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
+
 ## CLI Commands
 
 ```bash
 sungen add --screen <name> --path <url-path>               # Scaffold screen directories
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
-sungen generate --screen <name>                              # Compile .feature → .spec.ts
+sungen generate --screen <name>                              # Compile .feature → .spec.ts (runtime data)
+sungen generate --screen <name> --inline-data                # Compile with hardcoded data (legacy)
 sungen generate --all                                        # Compile all screens
 sungen delivery                                              # Export all screens → CSV + XLSX
 sungen delivery <screen>                                     # Export a single screen

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -151,6 +151,14 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
 | `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (base.ts fixture) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (base.ts fixture) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (base.ts fixture) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (base.ts fixture) |
+| `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
+| `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
+| `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 
 ### @extend behavior
 
@@ -175,30 +183,28 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
-| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 
 ## Background vs @steps/@extend
 
-**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+Both `Background` and `@steps`/`@extend` are valid — they serve different purposes.
 
-**Why:**
-- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
-- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
-- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+| Pattern | Use when | Generates |
+|---|---|---|
+| `Background` | Simple shared setup (navigate to page) | `test.beforeEach()` |
+| `@steps`/`@extend` | Complex reusable flows with scope (dialog, frame) | Inline merged steps in `test()` |
 
-**Wrong:**
+**Use `Background` for simple navigation:**
 ```gherkin
 Background:
-  Given User is on [Kudos] page
-  When User click [Open] button
-  And User is on [Modal] dialog    ← keyword mismatch
+  Given User is on [Dashboard] page
 
-Scenario: VP-UI-001 Title visible
-  Then User see [Title] heading
+Scenario: View stats
+  Then User see [Revenue Chart] section
 ```
 
-**Correct:**
+**Use `@steps`/`@extend` when scope matters (dialog, frame):**
 ```gherkin
 @steps:open_modal
 Scenario: Open modal
@@ -211,3 +217,50 @@ Scenario: VP-UI-001 Title visible
   Given User is on [Modal] dialog
   Then User see [Title] heading
 ```
+
+**Avoid `Background` with scope-dependent steps** — `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When). Use `@steps`/`@extend` instead.
+
+## Hooks & Cleanup
+
+Two layers for test lifecycle management. Prefer `@cleanup:*` tags (Layer 1) — they work with base.ts automatically. Use hook scenarios (Layer 2) only for custom logic.
+
+### Layer 1: `@cleanup:*` tags (automatic via base.ts)
+
+Feature-level tags that activate cleanup fixtures in base.ts. No Gherkin steps needed.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+@cleanup:forms
+Feature: User Management
+  Path: /users
+
+  Background:
+    Given User is on [User Management] page
+
+  Scenario: Create user shows form
+    When User click [Add User] button
+    Then User see [Create User] dialog
+
+  Scenario: Search user by name
+    When User fill [Search] field with {{search_name}}
+    Then User see [User Row] row
+```
+
+| Tag | What base.ts does after each test |
+|---|---|
+| `@cleanup:overlay` | Press Escape, click body, dismiss fixed overlays |
+| `@cleanup:forms` | Clear all input/textarea fields, reset selects |
+| `@cleanup:scroll` | Scroll to top of page |
+| `@cleanup:storage` | Clear sessionStorage |
+
+### Layer 2: `@afterEach` scenario (custom cleanup)
+
+Only when `@cleanup:*` tags aren't enough — feature-specific logic.
+
+### Layer 3: `@beforeAll` / `@afterAll` (optional)
+
+For one-time setup/teardown.
+
+**Rendering order in `.spec.ts`:**
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -112,20 +112,59 @@ Given User is on [Screen] page
 And User wait for [Page Title] heading is visible
 ```
 
+## Cleanup & Hooks
+
+### Auto-assign `@cleanup:*` tags based on screen sections
+
+After identifying screen sections, add appropriate `@cleanup:*` feature-level tags. These activate base.ts fixtures that auto-clean state between tests.
+
+| Screen has | Add tag | Why |
+|---|---|---|
+| Modal / Dialog / Drawer | `@cleanup:overlay` | Dismiss leftover overlays between tests |
+| Form & Inputs / Search / Filter | `@cleanup:forms` | Clear form fields, reset selects |
+| Long scrollable content | `@cleanup:scroll` | Scroll to top for consistent assertions |
+| Auth tokens / session data in tests | `@cleanup:storage` | Clear sessionStorage |
+| CI/CD or debug-heavy screens | `@screenshot:on-failure` | Auto-capture screenshot on test failure |
+
+**Always add `@cleanup:overlay`** if ANY section opens a dialog (Create/Add, Update/Edit, Delete confirmation). Most CRUD screens need it.
+
+**Always add `@cleanup:forms`** if the screen has inline search, filter dropdowns, or editable forms that persist between tests.
+
+### When to add `@afterEach` hook scenario
+
+Only when `@cleanup:*` tags aren't enough — feature-specific cleanup logic:
+- Reset a dropdown filter to default value (not just clear)
+- Navigate away from a sub-tab back to the main tab
+- Close a specific sidebar panel
+
+```gherkin
+@afterEach
+Scenario: Reset filters to default
+  When User select [Status Filter] dropdown with {{default_status}}
+```
+
+### `@beforeAll` / `@afterAll` — optional, low priority
+
+For one-time setup/teardown. Most screens don't need these.
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
-**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+`Background` is valid for simple shared setup (navigate to page). Use `@steps`/`@extend` for complex flows with scope (dialog, frame).
 
 ```gherkin
 @auth:role
+@cleanup:overlay
+@cleanup:forms
 Feature: <Screen> Screen
 
+  Background:
+    Given User is on [Screen] page
+
   # Shared setup — NO priority tag on @steps
   @steps:open_form
   Scenario: Open form
-    Given User is on [Screen] page
     When User click [Create] button
     Then User see [Form] dialog
 
@@ -165,6 +204,18 @@ Feature: <Screen> Screen
 
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix. Scenario name must use the **same element type** as the steps — e.g., if the step uses `dialog`, write "dialog opens" not "modal opens".
 
-**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.
+**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section. Data is loaded **at runtime** — keys become runtime lookups, not hardcoded strings. The same compiled test works across environments.
+
+**Environment-specific data**: For values that differ per environment (credentials, URLs, test users), create `<screen>.<env>.yaml` alongside the base file. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides. Structure env YAML with the same keys, only including values that change:
+
+```yaml
+# login.yaml (base)
+valid_email: admin@dev.example.com
+valid_password: DevPass123
+
+# login.staging.yaml (override for staging)
+valid_email: admin@staging.example.com
+valid_password: StagingPass456
+```
 
 **Do NOT generate**: `selectors.yaml` (created during run-test), Playwright code (sungen compiles).

package/src/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -18,7 +18,7 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile: `sungen generate --screen <screen>`.
+4. Compile: `sungen generate --screen <screen>` (default: runtime data loading from YAML). Use `--inline-data` only if user requests compile-time hardcoded values.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 

package/src/orchestrator/templates/ai-instructions/copilot-config.md

@@ -40,7 +40,9 @@ After each command completes, present the next actions as selectable options. Ne
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
 ├── selectors/<screen>.yaml        # Element locators (generated during run-test)
-├── test-data/<screen>.yaml        # Test data variables
+├── test-data/<screen>.yaml        # Test data variables (loaded at runtime)
+├── test-data/<screen>.staging.yaml    # Environment override (optional)
+├── test-data/<screen>.production.yaml # Environment override (optional)
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
@@ -49,12 +51,19 @@ qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen-deli
 qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ```
 
+## Test Data
+
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+
+**Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
+
 ## CLI Commands
 
 ```bash
 sungen add --screen <name> --path <url-path>               # Scaffold screen directories
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
-sungen generate --screen <name>                              # Compile .feature → .spec.ts
+sungen generate --screen <name>                              # Compile .feature → .spec.ts (runtime data)
+sungen generate --screen <name> --inline-data                # Compile with hardcoded data (legacy)
 sungen generate --all                                        # Compile all screens
 sungen delivery                                              # Export all screens → CSV + XLSX
 sungen delivery <screen>                                     # Export a single screen

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -151,6 +151,14 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
 | `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (base.ts fixture) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (base.ts fixture) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (base.ts fixture) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (base.ts fixture) |
+| `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
+| `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
+| `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 
 ### @extend behavior
 
@@ -175,30 +183,28 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
-| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 
 ## Background vs @steps/@extend
 
-**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+Both `Background` and `@steps`/`@extend` are valid — they serve different purposes.
 
-**Why:**
-- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
-- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
-- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+| Pattern | Use when | Generates |
+|---|---|---|
+| `Background` | Simple shared setup (navigate to page) | `test.beforeEach()` |
+| `@steps`/`@extend` | Complex reusable flows with scope (dialog, frame) | Inline merged steps in `test()` |
 
-**Wrong:**
+**Use `Background` for simple navigation:**
 ```gherkin
 Background:
-  Given User is on [Kudos] page
-  When User click [Open] button
-  And User is on [Modal] dialog    ← keyword mismatch
+  Given User is on [Dashboard] page
 
-Scenario: VP-UI-001 Title visible
-  Then User see [Title] heading
+Scenario: View stats
+  Then User see [Revenue Chart] section
 ```
 
-**Correct:**
+**Use `@steps`/`@extend` when scope matters (dialog, frame):**
 ```gherkin
 @steps:open_modal
 Scenario: Open modal
@@ -211,3 +217,70 @@ Scenario: VP-UI-001 Title visible
   Given User is on [Modal] dialog
   Then User see [Title] heading
 ```
+
+**Avoid `Background` with scope-dependent steps** — `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When). Use `@steps`/`@extend` instead.
+
+## Hooks & Cleanup
+
+Two layers for test lifecycle management. Prefer `@cleanup:*` tags (Layer 1) — they work with base.ts automatically. Use hook scenarios (Layer 2) only for custom logic.
+
+### Layer 1: `@cleanup:*` tags (automatic via base.ts)
+
+Feature-level tags that activate cleanup fixtures in base.ts. No Gherkin steps needed.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+@cleanup:forms
+Feature: User Management
+  Path: /users
+
+  Background:
+    Given User is on [User Management] page
+
+  Scenario: Create user shows form
+    When User click [Add User] button
+    Then User see [Create User] dialog
+    # After test: overlay auto-dismissed, forms auto-cleared by base.ts
+
+  Scenario: Search user by name
+    When User fill [Search] field with {{search_name}}
+    Then User see [User Row] row
+    # After test: search field auto-cleared by base.ts
+```
+
+| Tag | What base.ts does after each test |
+|---|---|
+| `@cleanup:overlay` | Press Escape, click body, dismiss fixed overlays |
+| `@cleanup:forms` | Clear all input/textarea fields, reset selects |
+| `@cleanup:scroll` | Scroll to top of page |
+| `@cleanup:storage` | Clear sessionStorage |
+
+### Layer 2: `@afterEach` scenario (custom cleanup)
+
+Only when `@cleanup:*` tags aren't enough — feature-specific logic.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+Feature: Dashboard
+  Path: /dashboard
+
+  Background:
+    Given User is on [Dashboard] page
+
+  @afterEach
+  Scenario: Reset dashboard filters
+    When User select [Date Filter] dropdown with {{default_period}}
+
+  Scenario: Filter by last week
+    When User select [Date Filter] dropdown with {{last_week}}
+    Then User see [Revenue Chart] section
+```
+
+### Layer 3: `@beforeAll` / `@afterAll` (optional)
+
+For one-time setup/teardown. Low priority — most e2e tests don't need these.
+
+**Rendering order in `.spec.ts`:**
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -112,20 +112,59 @@ Given User is on [Screen] page
 And User wait for [Page Title] heading is visible
 ```
 
+## Cleanup & Hooks
+
+### Auto-assign `@cleanup:*` tags based on screen sections
+
+After identifying screen sections, add appropriate `@cleanup:*` feature-level tags. These activate base.ts fixtures that auto-clean state between tests.
+
+| Screen has | Add tag | Why |
+|---|---|---|
+| Modal / Dialog / Drawer | `@cleanup:overlay` | Dismiss leftover overlays between tests |
+| Form & Inputs / Search / Filter | `@cleanup:forms` | Clear form fields, reset selects |
+| Long scrollable content | `@cleanup:scroll` | Scroll to top for consistent assertions |
+| Auth tokens / session data in tests | `@cleanup:storage` | Clear sessionStorage |
+| CI/CD or debug-heavy screens | `@screenshot:on-failure` | Auto-capture screenshot on test failure |
+
+**Always add `@cleanup:overlay`** if ANY section opens a dialog (Create/Add, Update/Edit, Delete confirmation). Most CRUD screens need it.
+
+**Always add `@cleanup:forms`** if the screen has inline search, filter dropdowns, or editable forms that persist between tests.
+
+### When to add `@afterEach` hook scenario
+
+Only when `@cleanup:*` tags aren't enough — feature-specific cleanup logic:
+- Reset a dropdown filter to default value (not just clear)
+- Navigate away from a sub-tab back to the main tab
+- Close a specific sidebar panel
+
+```gherkin
+@afterEach
+Scenario: Reset filters to default
+  When User select [Status Filter] dropdown with {{default_status}}
+```
+
+### `@beforeAll` / `@afterAll` — optional, low priority
+
+For one-time setup/teardown. Most screens don't need these.
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
-**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+`Background` is valid for simple shared setup (navigate to page). Use `@steps`/`@extend` for complex flows with scope (dialog, frame).
 
 ```gherkin
 @auth:role
+@cleanup:overlay
+@cleanup:forms
 Feature: <Screen> Screen
 
+  Background:
+    Given User is on [Screen] page
+
   # Shared setup — NO priority tag on @steps
   @steps:open_form
   Scenario: Open form
-    Given User is on [Screen] page
     When User click [Create] button
     Then User see [Form] dialog
 
@@ -171,6 +210,18 @@ Feature: <Screen> Screen
 
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix. Scenario name must use the **same element type** as the steps — e.g., if the step uses `dialog`, write "dialog opens" not "modal opens".
 
-**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.
+**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section. Data is loaded **at runtime** — keys become runtime lookups, not hardcoded strings. The same compiled test works across environments.
+
+**Environment-specific data**: For values that differ per environment (credentials, URLs, test users), create `<screen>.<env>.yaml` alongside the base file. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides. Structure env YAML with the same keys, only including values that change:
+
+```yaml
+# login.yaml (base)
+valid_email: admin@dev.example.com
+valid_password: DevPass123
+
+# login.staging.yaml (override for staging)
+valid_email: admin@staging.example.com
+valid_password: StagingPass456
+```
 
 **Do NOT generate**: `selectors.yaml` (created during run-test), Playwright code (sungen compiles).

package/src/orchestrator/templates/specs-base.ts

@@ -1,12 +1,27 @@
 import { test as base, expect } from '@playwright/test';
 import type { BrowserContext, Page } from '@playwright/test';
 
+type CleanupConfig = {
+  overlay?: boolean;
+  forms?: boolean;
+  scroll?: boolean;
+  storage?: boolean;
+};
+
 // Share one context per storageState — avoids creating multiple sessions
 // that trigger server rate limiting or session invalidation
 const contextCache = new Map<string, { context: BrowserContext; page: Page }>();
 const GOTO_PATCHED = Symbol('goto-patched');
 
-const test = base.extend({
+const test = base.extend<{
+  autoCleanup: CleanupConfig;
+  screenshotOnFailure: boolean;
+  _autoCleanup: void;
+  _autoScreenshot: void;
+}>({
+  autoCleanup: [{}, { option: true }],
+  screenshotOnFailure: [false, { option: true }],
+
   page: async ({ browser, storageState }, use) => {
     if (storageState) {
       const cacheKey = typeof storageState === 'string' ? storageState : JSON.stringify(storageState);
@@ -28,12 +43,6 @@ const test = base.extend({
           try {
             const currentPath = new URL(page.url()).pathname;
             if (currentPath === url || currentPath === url + '/') {
-              // Dismiss any open overlays (dropdowns, dialogs) from previous test
-              await page.keyboard.press('Escape').catch(() => {});
-              await page.locator('body').click({ position: { x: 1, y: 1 }, force: true }).catch(() => {});
-
-              // Safety check: if a fixed-position overlay (modal/dialog) is still present, full reload
-              // eslint-disable-next-line no-eval -- runs in browser context via Playwright
               const hasOverlay = await page.evaluate(`(() => {
                 const el = document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2);
                 if (!el) return false;
@@ -68,6 +77,55 @@ const test = base.extend({
       await context.close();
     }
   },
+
+  // Auto-cleanup fixture: runs teardown after each test based on @cleanup:* tags
+  _autoCleanup: [async ({ page, autoCleanup }, use) => {
+    await use();
+
+    if (autoCleanup.overlay) {
+      await page.keyboard.press('Escape').catch(() => {});
+      await page.locator('body').click({ position: { x: 1, y: 1 }, force: true }).catch(() => {});
+      // Dismiss persistent fixed overlays (modals, dialogs)
+      const hasOverlay = await page.evaluate(`(() => {
+        const el = document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2);
+        if (!el) return false;
+        let current = el;
+        while (current && current !== document.body) {
+          if (getComputedStyle(current).position === 'fixed') return true;
+          current = current.parentElement;
+        }
+        return false;
+      })()`).catch(() => false);
+      if (hasOverlay) {
+        await page.keyboard.press('Escape').catch(() => {});
+      }
+    }
+    if (autoCleanup.forms) {
+      await page.evaluate(`(() => {
+        document.querySelectorAll('input:not([type=hidden]):not([type=submit])').forEach(el => { el.value = ''; });
+        document.querySelectorAll('textarea').forEach(el => { el.value = ''; });
+        document.querySelectorAll('select').forEach(el => { el.selectedIndex = 0; });
+      })()`).catch(() => {});
+    }
+    if (autoCleanup.scroll) {
+      await page.evaluate('window.scrollTo(0, 0)').catch(() => {});
+    }
+    if (autoCleanup.storage) {
+      await page.evaluate('sessionStorage.clear()').catch(() => {});
+    }
+  }, { auto: true }],
+
+  // Auto-screenshot fixture: captures screenshot on test failure
+  _autoScreenshot: [async ({ page, screenshotOnFailure }, use, testInfo) => {
+    await use();
+
+    if (screenshotOnFailure && testInfo.status !== testInfo.expectedStatus) {
+      await testInfo.attach('screenshot', {
+        body: await page.screenshot(),
+        contentType: 'image/png',
+      });
+    }
+  }, { auto: true }],
 });
 
 export { test, expect };

package/src/orchestrator/templates/specs-test-data.ts

@@ -0,0 +1,66 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'yaml';
+
+export class TestDataLoader {
+  private data: Record<string, any>;
+
+  private constructor(data: Record<string, any>) {
+    this.data = data;
+  }
+
+  /**
+   * Load test data for a screen/feature combination.
+   *
+   * Priority (later wins):
+   * 1. {feature}.yaml — base data
+   * 2. {feature}.{SUNGEN_ENV}.yaml — environment-specific (if SUNGEN_ENV set)
+   */
+  static load(screenName: string, featureName: string): TestDataLoader {
+    const baseDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'test-data');
+    const env = process.env.SUNGEN_ENV;
+
+    let data = loadYamlSync(path.join(baseDir, `${featureName}.yaml`)) || {};
+
+    if (env) {
+      const envData = loadYamlSync(path.join(baseDir, `${featureName}.${env}.yaml`));
+      if (envData) data = deepMerge(data, envData);
+    }
+
+    return new TestDataLoader(data);
+  }
+
+  get(key: string): string {
+    const parts = key.split('.');
+    let current: any = this.data;
+    for (const part of parts) {
+      if (current == null || typeof current !== 'object') {
+        throw new Error(`Test data key not found: ${key} (failed at '${part}')`);
+      }
+      current = current[part];
+    }
+    if (current === undefined || current === null) {
+      throw new Error(`Test data key not found: ${key}`);
+    }
+    return String(current);
+  }
+}
+
+function loadYamlSync(filePath: string): Record<string, any> | null {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return yaml.parse(content) || null;
+}
+
+function deepMerge(base: Record<string, any>, override: Record<string, any>): Record<string, any> {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value && typeof value === 'object' && !Array.isArray(value) &&
+        result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+      result[key] = deepMerge(result[key], value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}