@sun-asterisk/sungen 2.2.3 → 2.3.1

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -124,6 +124,24 @@ To determine the correct `nth` offset, count how many matching elements appear b
 
 ---
 
+### Step 4b: Handle Detail Screens with Dynamic IDs
+
+For screens like `/admin/users/:id` or `/products/:slug`:
+1. Navigate to the **list page** first via MCP browser to find a real record ID
+2. Use that ID in the page selector value
+3. Use `User is on [X] page` — sungen resolves the path from the selector
+
+```yaml
+# selectors.yaml — full path with real ID
+user detail:
+  type: 'page'
+  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
+```
+
+Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+
+---
+
 ### Step 5: Handle SPA / Client-side Routing
 
 Many modern apps (Next.js, Nuxt, SvelteKit, etc.) return the same HTML shell for all URLs and route client-side. `domcontentloaded` fires on the shell before the target page renders.
@@ -188,54 +206,77 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 
 ---
 
-### Fix Loop on Test Failure (Batched Strategy)
+### Proactive Selector Validation (before running tests)
 
-Running all tests every iteration is slow. Use a batched approach to fix faster:
+**Most failures are selector mismatches.** Validate selectors against the live page BEFORE running any test — this eliminates slow compile→run→read→fix cycles.
 
-```
-1. INITIAL RUN — run ALL tests, collect full failure list
-     npx playwright test <spec> --reporter=line
+After generating `selectors.yaml` (Step 3), verify each entry:
 
-2. BATCHED FIX LOOP (max 5 attempts):
-     a. Read test output → group failures by root cause:
-        - Same selector broken → 1 fix covers many tests
-        - Same error type (strict mode, timeout, text mismatch)
-     b. Fix selectors.yaml or test-data.yaml for current batch
-     c. Recompile: sungen generate --screen <screen>
-     d. Re-run ONLY previously-failing tests (max 20):
-        npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|VP-VAL-001" --reporter=line
-     e. If batch passes → pick next batch of remaining failures
-     f. If batch still fails → fix and retry (counts toward max 5)
-
-3. FINAL CONFIRMATION — run ALL tests once:
-     npx playwright test <spec> --reporter=line
-     This catches regressions from selector changes.
+#### How to validate
 
-4. If still failing after 5 fix attempts → ask user about direct .spec.ts fix
+Use `browser_evaluate` to check if each selector actually finds an element on the page:
+
+```js
+// Validate a role selector
+document.querySelectorAll('[role="button"]').length;
+// or check accessible name
+Array.from(document.querySelectorAll('button'))
+  .filter(el => el.textContent.includes('Submit') || el.getAttribute('aria-label')?.includes('Submit'))
+  .length;
 ```
 
-#### Building the `--grep` pattern
+Or use `browser_snapshot` and cross-check:
+1. Read all `[Reference]` entries from `selectors.yaml`
+2. Take a `browser_snapshot`
+3. For each entry, verify the element exists in the snapshot
+4. Fix mismatches immediately — no test run needed
+
+#### What to check
+
+| Selector type | Validation method |
+|---|---|
+| `role` + `name` | Search snapshot for `role "name"` text |
+| `testid` | `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')` |
+| `placeholder` | Search snapshot for textbox with placeholder |
+| `locator` (CSS) | `browser_evaluate`: `document.querySelector('xxx')` |
+
+**Target: fix 80%+ of selector issues before the first test run.**
+
+---
+
+### Batched Test Execution
+
+After proactive validation, run tests in **batches of 20** for faster feedback:
 
-Extract scenario names from the failure output and join with `|`:
-```bash
-# Example: re-run only 3 failing tests
-npx playwright test <spec> --grep "VP-VAL-001|VP-VAL-002|VP-VAL-003" --reporter=line
 ```
+1. COMPILE — sungen generate --screen <screen>
 
-- Max 20 test names per `--grep` to keep the pattern manageable
-- If >20 failures share the same root cause, fix the cause and run the first 20 to verify
+2. BATCH RUN — run 20 tests at a time:
+     npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
+
+3. IF FAILURES in batch:
+     a. Group failures by root cause (same selector, same error type)
+     b. Fix selectors.yaml or test-data.yaml
+     c. Recompile, re-run only failing tests from this batch
+     d. If fixed → move to next batch
+
+4. NEXT BATCH — repeat with next 20 tests
+
+5. FINAL CONFIRMATION — run ALL tests once:
+     npx playwright test <spec> --reporter=line
+
+6. If still failing after 5 fix attempts per batch → ask user about direct .spec.ts fix
+```
 
 #### Grouping failures by root cause
 
 Common patterns where 1 fix resolves many failures:
-- **Same selector** — e.g., all `[Email Error]` tests fail → fix `email error` in selectors.yaml once
+- **Same selector** — e.g., all `[Email Error]` tests fail → fix once
 - **Same error type** — e.g., all `strict mode violation` → add `exact: true` or `nth`
-- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern (inputs have no text)
+- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern
 
 Fix the root cause first, verify with the batch, then move on.
 
-**Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
-
 ---
 
 ### Key Rules (from sungen-selector-keys)

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

@@ -33,6 +33,46 @@ For options 1 and 2:
 For option 3:
 - Overwrite both `.feature` and `test-data.yaml` completely
 
+### Requirements-Driven Generation
+
+When `qa/screens/<screen>/requirements/` exists, use it as the **primary source** for test case generation. This produces higher quality tests because requirements contain exact validation messages, field constraints, business rules, and states.
+
+#### Reading Requirements
+
+1. **`spec.md`** (primary) — structured screen specification:
+   - **Sections** → map directly to test case sections
+   - **Fields table** → generate boundary value tests (min/max constraints), required field tests, format tests
+   - **Validation Rules table** → generate exact assertion tests using the error messages as `{{test_data}}` values
+   - **Actions table** → generate interaction tests (click, submit, navigate)
+   - **States table** → generate state transition tests (loading, error, success, disabled)
+   - **Business Rules** → generate logic tests (limits, permissions, conditional behavior)
+   - **Accessibility** → generate tab-order and aria tests
+
+2. **`ui/`** (supplementary) — screenshots, mockups, design images:
+   - Read images to understand layout, element positions, visual states
+   - Cross-reference with spec.md — identify elements visible in UI but missing from spec
+   - Use for UI/UX viewpoint tests (element visibility, placement, responsive)
+
+3. **`notes.md`** (supplementary) — free-form edge cases, decisions, known issues:
+   - Extract edge cases → add to test coverage
+   - Flag known issues → add TODO scenarios
+
+#### How Requirements Improve Each Viewpoint
+
+| Viewpoint | Without Requirements | With Requirements |
+|-----------|---------------------|-------------------|
+| **UI/UX** | "see [Field] is visible" (generic) | "see [Field] field" + verify label, placeholder, default from spec |
+| **Validation** | "submit empty → see error" (vague) | "submit empty email → see {{email_required_error}}" with exact message from spec |
+| **Logic** | Based on observed page behavior | Business rules drive specific tests (lockout after N attempts, session expiry) |
+| **Security** | Generic injection tests | Role-based tests from auth requirements, permission-specific scenarios |
+
+#### Merging Requirements + Live Page
+
+If the user also explores the live page:
+- **Verify** spec.md against actual page — flag mismatches (e.g., field in spec but not on page)
+- **Supplement** — discover elements on page not in spec (e.g., footer links, tooltips)
+- **Exact text** — capture actual placeholder text, button labels, error messages from live page and update test-data accordingly
+
 ### Page Exploration & Auth
 
 Use Playwright MCP to explore the live page. If the page requires authentication:
@@ -55,26 +95,7 @@ Use Playwright MCP to explore the live page. If the page requires authentication
 
 #### Detail screens with dynamic IDs
 
-For screens like `/admin/users/:id` or `/products/:slug`:
-1. Navigate to the **list page** first via MCP browser to find a real record ID
-2. Use that ID in the page selector value
-3. Use `User is on [X] page` — sungen resolves the path from the selector
-
-```yaml
-# selectors.yaml — full path with real ID (generated during make-test)
-user detail:
-  type: 'page'
-  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
-```
-
-```gherkin
-Scenario: VP-UI-001 User detail displays name
-  Given User is on [User Detail] page
-  And User wait for [User Name] heading is visible
-  Then User see [User Name] heading with {{user_name}}
-```
-
-Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+For screens like `/admin/users/:id` or `/products/:slug`, write Gherkin normally (`User is on [User Detail] page`). The real ID will be resolved during `/sungen-make-test` when selectors are generated from the live page. See `sungen-selector-fix` skill for details.
 
 ### Section-Focused Approach
 
@@ -113,72 +134,58 @@ For each selected section, generate **20+ scenarios per applicable viewpoint**.
 
 Present a test plan summary and wait for user confirmation before generating files.
 
+### Assertion & Review Quality
+
+For assertion quality rules, action-result coherence rules, and the 9-point quality review checklist, see the `sungen-gherkin-review` skill. That skill is auto-loaded during the self-review step.
+
 ### Viewpoint Categories
 
 | VP Category | Description |
 |---|---|
-| **UI/UX** | Default appearance, element visibility, default states |
-| **Validation** | Input validation, error messages, edge cases. **Must explore live page via MCP to capture actual error messages before writing tests. Use `User see {{error_var}}` pattern — never assert just "is visible".** |
+| **UI/UX** | Default appearance, default values/text, default states. Group related elements per scenario. |
+| **Validation** | Input validation, error messages, edge cases. **Assert exact error messages via `User see [T] with {{error_var}}`** — store texts in test-data.yaml. |
 | **Logic** | Business logic, interactions, state changes |
 | **Security** | Auth guards, injection, permission checks |
 
 ### Coverage Checklist per Section Pattern
 
-Apply the relevant checklist based on the section pattern:
-
 #### Form sections
-- **UI/UX**: All fields visible, labels correct, default values, placeholder text, required indicators
-- **Validation**: Empty submit, each required field empty, invalid format (email, phone, URL), min/max length, special chars, unicode, XSS, SQL injection, whitespace-only, boundary values
-- **Validation**: Empty submit, each required field empty, invalid format (email, phone, URL), min/max length, special chars, unicode, XSS, SQL injection, whitespace-only, boundary values — **assert exact error messages via `User see {{error_var}}`**, store texts in test-data.yaml
-- **Logic**: Successful submit, submit with all optional fields, edit existing record, cancel resets form, field dependencies (show/hide), auto-complete, date range validation
-- **Security**: CSRF protection, unauthorized submit, role-based field visibility, input sanitization
+- **UI/UX**: All fields + labels + default values in 1-2 grouped scenarios. Default states (button enabled/disabled, checkbox unchecked). Placeholder text via `with {{placeholder}}`.
+- **Validation**: Empty submit → verify all error messages. Each required field empty individually → verify specific error. Invalid formats → verify specific error. Boundary values (min/max length). Special chars, unicode, XSS, SQL injection.
+- **Logic**: Successful submit → verify success state/redirect. Edit existing → verify pre-filled values. Cancel → verify form resets. Field dependencies (show/hide).
+- **Security**: Unauthorized submit, role-based field visibility, input sanitization
 
 #### Data Table sections
-- **UI/UX**: All columns visible, column headers, row data displays correctly, empty state, loading state, action buttons visible
-- **Validation**: N/A (read-only) or inline edit validation
-- **Logic**: Sort ascending/descending per sortable column, filter by each column, search within table, row action menu (edit/delete/view), bulk select, bulk action, row click navigation, column resize
-- **Security**: Cannot access other users' data, action permissions per role, data not exposed in DOM
+- **UI/UX**: All column headers in one scenario (`User see [Col] column in [Table] table`). Row data displays with correct values. Empty state message. Action buttons per row.
+- **Logic**: Sort ascending/descending. Filter by column. Search. Row actions (edit/delete/view). Bulk select + action.
+- **Security**: Action permissions per role
 
 #### Search & Filter sections
-- **UI/UX**: Search field visible, filter buttons visible, clear button state
-- **Validation**: Empty search, special chars, SQL injection, XSS, very long text, unicode/emoji, whitespace, partial match, case insensitive
-- **Logic**: Apply single filter, combine multiple filters, clear single filter, clear all filters, search + filter combined, filter persists across pagination, no results state
-- **Security**: Injection via search, injection via filter params
+- **UI/UX**: Search field + filter buttons + clear button states in one scenario
+- **Validation**: Empty search, special chars, injection, long text, unicode
+- **Logic**: Apply/clear single filter, combine filters, no results state with message
+- **Security**: Injection via search/filter params
 
 #### Pagination sections
-- **UI/UX**: Page indicator visible, previous disabled on page 1, next enabled
-- **Logic**: Next page, previous page, navigate to last page, boundary (first/last), page indicator updates, data refreshes on navigation
-- **Security**: Filters persist across pages, search persists, cannot access page beyond max
+- **UI/UX**: Page indicator + button states (previous disabled on page 1, next enabled)
+- **Logic**: Navigate pages, boundary behavior, indicator updates
 
 #### Modal / Dialog sections
-- **UI/UX**: Modal opens, close button visible, overlay visible, form fields inside modal
-- **Validation**: Submit empty form in modal, field validation inside modal
-- **Logic**: Open modal, close with X, close with Escape, close with overlay click, submit success closes modal, submit error keeps modal open
-- **Security**: Cannot open unauthorized modals, CSRF on modal submit
-
-#### Card Grid / List sections
-- **UI/UX**: Cards display all expected fields (title, image, description, metadata), empty state, loading state
-- **Logic**: Click card navigates to detail, load more / infinite scroll, card action buttons (like, share, delete), responsive layout
-- **Security**: User-generated content sanitized, cannot access other users' cards
-
-#### Carousel / Slider sections
-- **UI/UX**: Arrows visible, indicators visible, current slide highlighted
-- **Logic**: Next slide, previous slide, wrap at end, auto-play, indicator click navigates, swipe gesture
-- **Security**: N/A
+- **UI/UX**: Modal content + all fields + close button in one scenario
+- **Validation**: Field validation inside modal with exact errors
+- **Logic**: Open/close methods (X, Escape, overlay), submit success/error behavior
 
 #### Tabs / Accordion sections
-- **UI/UX**: All tabs visible, active tab highlighted, default tab selected
-- **Logic**: Switch tabs, content updates per tab, deep link to tab, accordion expand/collapse, only one accordion open at a time
-- **Security**: Tab content respects permissions
+- **UI/UX**: All tab labels + active tab highlighted + default tab content
+- **Logic**: Switch tabs → verify content changes, accordion expand/collapse
 
 ### General Coverage Dimensions (aim for 20+ total per viewpoint)
 
-**Happy paths (3-5):** Standard flow, all optional fields, minimum required
-**Edge cases (5-8):** Empty, max length, special chars, unicode/CJK/emoji, whitespace, leading/trailing spaces, overflow
-**Boundary values (3-5):** At min/max limit, one above/below, zero/null
-**Negative cases (3-5):** Invalid format, missing required, wrong type, injection attempts
-**State transitions (2-4):** Before/after action, undo, cancel mid-flow
-**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos, different roles
+**Happy paths (3-5):** Standard flow with full assertion of result state
+**Edge cases (5-8):** Empty, max length, special chars, unicode, whitespace, boundary values
+**Negative cases (3-5):** Invalid format, missing required, wrong type, exact error messages
+**State transitions (2-4):** Before/after action, verify both old and new state
+**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos
 
 ### SPA Wait-For Steps
 
@@ -209,24 +216,37 @@ Feature: <Screen> Screen
   # Section: Create User Form
   # ============================================================
 
-  # --- UI/UX (20+) ---
+  # --- UI/UX ---
 
-  Scenario: VP-UI-001 Name field is visible
-    ...
+  Scenario: VP-UI-001 Form displays all fields with correct defaults
+    Given User is on [Create User] page
+    Then User see [Create User] heading with {{form_title}}
+    And User see [Name] field
+    And User see [Email] field
+    And User see [Role] dropdown with {{default_role}}
+    And User see [Submit] button is disabled
+    And User see [Cancel] button is enabled
 
-  # --- Validation (20+) ---
+  # --- Validation ---
 
-  Scenario: VP-VAL-001 Submit with empty name
-    ...
+  Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Create User] page
+    When User click [Submit] button
+    Then User see [Name error] message with {{name_required_error}}
+    And User see [Email error] message with {{email_required_error}}
 
   # ============================================================
   # Section: User Table
   # ============================================================
 
-  # --- UI/UX (20+) ---
+  # --- UI/UX ---
 
-  Scenario: VP-UI-025 Table displays all columns
-    ...
+  Scenario: VP-UI-010 Table displays all columns
+    Given User is on [Users] page
+    Then User see [Name] column in [Users] table
+    And User see [Email] column in [Users] table
+    And User see [Status] column in [Users] table
+    And User see [Actions] column in [Users] table
 ```
 
 **Naming convention:** `VP-<CATEGORY>-<NNN>` prefix in Scenario name.

package/dist/orchestrator/templates/readme.md

@@ -15,7 +15,11 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 ├── qa/screens/<name>/
 │   ├── features/         # .feature files (Gherkin)
 │   ├── selectors/        # Element locator YAML mappings
-│   └── test-data/        # Test data YAML values
+│   ├── test-data/        # Test data YAML values
+│   └── requirements/     # Screen specs, UI designs, notes
+│       ├── spec.md       # Structured screen specification
+│       ├── ui/           # Screenshots, mockups, design images
+│       └── notes.md      # Edge cases, decisions (optional)
 ├── specs/
 │   └── generated/        # Auto-generated Playwright tests
 ├── .claude/
@@ -53,7 +57,7 @@ Use AI commands (Claude Code or GitHub Copilot) to drive the workflow:
 |---|---|
 | `/sungen:add-screen` | `/sungen-add-screen` |
 
-Scaffolds `qa/screens/<name>/` with empty feature, selectors, and test-data files, then asks if you want to create test cases.
+Scaffolds `qa/screens/<name>/` with empty feature, selectors, test-data, and requirements files. Fill `requirements/spec.md` with screen specs before creating test cases for higher quality output.
 
 ### Step 2: Create test cases
 
@@ -62,10 +66,11 @@ Scaffolds `qa/screens/<name>/` with empty feature, selectors, and test-data file
 | `/sungen:make-tc login` | `/sungen-make-tc login` |
 
 AI acts as a **Senior QA Engineer**:
-1. Explores the live page via Playwright MCP (asks user to log in if auth needed)
-2. Identifies screen sections → asks user which to focus on
-3. Generates **20+ scenarios per viewpoint** (UI/UX, Validation, Logic, Security) for each section
-4. Confirms test plan before generating `.feature` + `test-data.yaml`
+1. Reads `requirements/spec.md` for screen specs (fields, validation, business rules, states)
+2. Optionally explores the live page via Playwright MCP to verify and supplement
+3. Identifies screen sections → asks user which to focus on
+4. Generates **20+ scenarios per viewpoint** (UI/UX, Validation, Logic, Security) for each section
+5. Confirms test plan before generating `.feature` + `test-data.yaml`
 
 ### Step 3: Compile & run tests
 
@@ -136,8 +141,8 @@ User <action> [<Target>] <type> with {{<Value>}}
 | Assert text | `User see [Title] heading with {{title}}` |
 | Assert state | `User see [Submit] button is disabled` |
 | Wait for | `User wait for [Modal] dialog is visible` |
-| Table row | `User see [Users] table has row with {{name}}` |
-| Table column | `User see [Users] table has [Email] column` |
+| Table row | `User see [Users] table row with {{name}}` |
+| Table column | `User see [Email] column in [Users] table` |
 
 States: `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/commands/update.ts

@@ -0,0 +1,18 @@
+import { Command } from 'commander';
+
+export function registerUpdateCommand(program: Command): void {
+  program
+    .command('update')
+    .description('Update AI rules, commands, and skills to the latest version')
+    .option('--dry-run', 'Show what would be updated without making changes')
+    .action(async (options: { dryRun?: boolean }) => {
+      try {
+        const { AIRulesUpdater } = require('../../orchestrator/ai-rules-updater');
+        const updater = new AIRulesUpdater(process.cwd());
+        await updater.update(options.dryRun ?? false);
+      } catch (error) {
+        console.error('❌ Update failed:', error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { registerInitCommand } from './commands/init';
 import { registerAddCommand } from './commands/add';
 import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
+import { registerUpdateCommand } from './commands/update';
 
 async function main() {
   const program = new Command();
@@ -16,7 +17,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.2.3');
+    .version('2.3.1');
 
   // Global options
   program
@@ -27,6 +28,7 @@ async function main() {
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
+  registerUpdateCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/generators/gherkin-parser/index.ts

@@ -14,6 +14,8 @@ export interface ParsedStep {
   elementType?: string; // Element type after [Selector] e.g., "button", "text", "link", "field"
   nth?: number; // Positional index from "[Element] field 3" → 3 (0 = not specified)
   featurePath?: string; // NEW: Feature path for page type (e.g., "/", "/dashboard")
+  parentRef?: string; // Parent scope reference: "in [Parent Name] parentType" → parentRef = "Parent Name"
+  parentType?: string; // Parent scope type: table, list, section, dialog, form
 }
 
 export interface ParsedScenario {
@@ -122,7 +124,20 @@ export class GherkinParser {
    * Parse a single step and extract selector/data references
    */
   private parseStep(step: Messages.Step): ParsedStep {
-    const text = step.text;
+    let text = step.text;
+
+    // === Extract parent scoping: "in [Parent Name] parentType" ===
+    // Must be extracted first so the parent [brackets] don't interfere with target selector extraction.
+    // Valid parent types: table, list, section, dialog, form
+    const parentMatch = text.match(/\s+in\s+\[([^\]]+)\]\s+(table|list|section|dialog|form)\b/i);
+    let parentRef: string | undefined;
+    let parentType: string | undefined;
+    if (parentMatch) {
+      parentRef = parentMatch[1];
+      parentType = parentMatch[2].toLowerCase();
+      // Remove parent scoping from text so it doesn't interfere with other parsing
+      text = text.slice(0, parentMatch.index) + text.slice(parentMatch.index! + parentMatch[0].length);
+    }
 
     // Extract selector reference: [Email Address] or [login:email_field] (legacy)
     // Support natural language and legacy formats
@@ -159,12 +174,14 @@ export class GherkinParser {
 
     return {
       keyword: step.keyword.trim(),
-      text,
+      text: step.text, // Preserve original text (with parent scoping) for pattern matching
       selectorRef,
       dataRef,
       value,
       elementType,
       nth,
+      parentRef,
+      parentType,
     };
   }
 

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/attribute-assertion.hbs

@@ -0,0 +1,3 @@
+{{#if pattern}}await expect({{> locator}}).toHaveAttribute('{{attribute}}', /{{dataValue}}/);
+{{else}}await expect({{> locator}}).toHaveAttribute('{{attribute}}', '{{dataValue}}');
+{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-base.hbs

@@ -1,3 +1,13 @@
+{{#if parentLocator}}{{parentLocator}}.{{#switch strategy~}}
+  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
+  {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{value}}'){{/case~}}
+  {{~#default}}locator('{{value}}'){{/default~}}
+{{~/switch}}{{else~}}
 {{#if scope}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{#switch strategy~}}
   {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
@@ -16,4 +26,5 @@
   {{~#case 'locator'}}{{> locator-strategies/locator}}{{/case~}}
   {{~#case 'id'}}{{> locator-strategies/id}}{{/case~}}
   {{~#default}}{{> locator-strategies/default}}{{/default~}}
-{{~/switch}}{{/if}}
+{{~/switch}}{{/if~}}
+{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator.hbs

@@ -1,3 +1,13 @@
+{{#if parentLocator}}{{parentLocator}}.{{#switch strategy~}}
+  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
+  {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{value}}'){{/case~}}
+  {{~#default}}locator('{{value}}'){{/default~}}
+{{~/switch}}{{> locator-nth}}{{else~}}
 {{#if scope}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{#switch strategy~}}
   {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
@@ -16,4 +26,5 @@
   {{~#case 'locator'}}{{> locator-strategies/locator}}{{/case~}}
   {{~#case 'id'}}{{> locator-strategies/id}}{{/case~}}
   {{~#default}}{{> locator-strategies/default}}{{/default~}}
-{{~/switch}}{{> locator-nth}}{{/if}}
+{{~/switch}}{{> locator-nth}}{{/if~}}
+{{/if}}

package/src/generators/test-generator/patterns/assertion-patterns.ts

@@ -279,6 +279,19 @@ export const assertionPatterns: StepPattern[] = [
         // Selector not in YAML or context issue - will use variable-only
       }
 
+      // --- Attribute assertion: toHaveAttribute ---
+      // When selector YAML has `attribute` field (e.g., attribute: 'src', 'href')
+      if (resolved.attribute) {
+        const code = context.templateEngine.renderStep('attribute-assertion', {
+          ...resolved,
+          dataValue,
+        });
+        return {
+          code,
+          comment: `Assert ${step.selectorRef} ${resolved.attribute} matches ${step.dataRef}`,
+        };
+      }
+
       // --- Input types: toHaveValue ---
       if (step.elementType && INPUT_TYPES.has(step.elementType)) {
         const code = context.templateEngine.renderStep('have-value-assertion', {

package/src/generators/test-generator/patterns/index.ts

@@ -72,6 +72,14 @@ export class PatternRegistry {
     // Prefer resolver (framework-agnostic) over generator (legacy)
     if (pattern.resolver) {
       const resolved = pattern.resolver(step, context);
+
+      // Auto-inject parent scoping if step has parentRef
+      if (step.parentRef && step.parentType) {
+        resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
+          step.parentRef, step.parentType, context
+        );
+      }
+
       const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
       return {
         code,
@@ -86,6 +94,39 @@ export class PatternRegistry {
     return null;
   }
 
+  /**
+   * Resolve parent scoping to a Playwright locator string.
+   * Tries YAML lookup first, falls back to auto-infer from parentType.
+   *
+   * Parent type → Playwright role:
+   *   table → 'table', list → 'list', section → 'region',
+   *   dialog → 'dialog', form → 'form'
+   */
+  private static resolveParentLocator(
+    parentRef: string, parentType: string, context: PatternContext
+  ): string {
+    // Try resolving from selectors YAML
+    try {
+      const resolved = context.selectorResolver.resolveSelector(
+        parentRef, context.featureName, parentType, 0
+      );
+      return context.renderLocator(resolved);
+    } catch {
+      // Fallback: auto-infer from parentType + parentRef as accessible name
+    }
+
+    const roleMap: Record<string, string> = {
+      table: 'table',
+      list: 'list',
+      section: 'region',
+      dialog: 'dialog',
+      form: 'form',
+    };
+    const role = roleMap[parentType] || parentType;
+    const escapedName = parentRef.replace(/'/g, "\\'");
+    return `page.getByRole('${role}', { name: '${escapedName}' })`;
+  }
+
   /**
    * Check if step matches a pattern matcher
    */