@sun-asterisk/sungen 2.6.0 → 2.6.2

package/src/generators/test-generator/code-generator.ts

@@ -48,6 +48,44 @@ function extractCleanupConfig(tags: string[]): string | undefined {
   return entries.map(key => `${key}: true`).join(', ');
 }
 
+/**
+ * Extract @cleanup:* tags into structured flags for serial mode afterEach
+ */
+function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean } | undefined {
+  const validKeys = ['overlay', 'forms', 'scroll', 'storage'] as const;
+  const flags: Record<string, boolean> = {};
+  let found = false;
+  for (const tag of tags) {
+    if (!tag.startsWith('@cleanup:')) continue;
+    const key = tag.replace('@cleanup:', '');
+    if (validKeys.includes(key as any)) {
+      flags[key] = true;
+      found = true;
+    }
+  }
+  return found ? flags : undefined;
+}
+
+/**
+ * Extract pass-through tags (non-functional) for Playwright { tag: [...] }.
+ * Any tag not recognized by sungen as functional → pass through.
+ */
+const FUNCTIONAL_TAG_PREFIXES = [
+  '@parallel', '@cleanup:', '@auth:', '@manual', '@no-auth',
+  '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
+  '@flow',
+];
+
+function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string | undefined {
+  const allTags = [...featureTags, ...scenarioTags];
+  const passThrough = allTags.filter(tag =>
+    !FUNCTIONAL_TAG_PREFIXES.some(prefix => tag.startsWith(prefix))
+  );
+  const unique = [...new Set(passThrough)];
+  if (unique.length === 0) return undefined;
+  return unique.map(t => `'${t}'`).join(', ');
+}
+
 /**
  * Check for @screenshot:on-failure tag
  */
@@ -190,8 +228,12 @@ export class CodeGenerator {
     const depth = outputSubdir ? outputSubdir.split(path.sep).length : 0;
     const basePath = depth > 0 ? Array(depth).fill('..').join('/') : '..';
 
-    // Generate imports using adapter
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath });
+    // Serial + @cleanup tags → need cleanupPage import from base
+    const isParallelFeature = (feature.tags || []).includes('@parallel');
+    const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
+    const needsCleanupImport = !isParallelFeature && hasCleanupTags;
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -340,10 +382,18 @@ export class CodeGenerator {
       }
     }
 
+    // Detect @parallel opt-out (default is serial)
+    const isParallel = (feature.tags || []).includes('@parallel');
+
     // Generate background if exists
     let background: string | undefined;
+    let backgroundSteps: Array<{ comment?: string; code: string }> | undefined;
     if (feature.background) {
-      background = await this.generateBeforeEach(feature.background);
+      if (isParallel) {
+        background = await this.generateBeforeEach(feature.background);
+      } else {
+        backgroundSteps = await this.generateBackgroundSteps(feature.background);
+      }
     }
 
     // Generate hook blocks
@@ -387,7 +437,8 @@ export class CodeGenerator {
       const code = await this.generateScenario(
         scenario,
         !!feature.background,
-        feature.tags || []
+        feature.tags || [],
+        isParallel
       );
       renderedScenarios.push({ code, authRole });
     }
@@ -414,6 +465,14 @@ export class CodeGenerator {
     // - Single group: flat structure (test.use at describe level if auth)
     // - Multiple groups: nested describes per auth role
     const needsGrouping = authGroups.length > 1;
+
+    if (needsGrouping && !isParallel) {
+      throw new Error(
+        `Feature "${feature.name}" has multiple auth groups but no @parallel tag.\n` +
+        `Serial mode uses a shared browser context — it cannot mix different auth roles.\n` +
+        `Fix: add @parallel tag to the feature.`
+      );
+    }
     const scenarios = renderedScenarios.map(s => s.code);
 
     // For single group, extract the auth role to put test.use at describe level
@@ -423,6 +482,7 @@ export class CodeGenerator {
 
     // Extract @cleanup:* tags for autoCleanup fixture config
     const cleanupConfig = extractCleanupConfig(feature.tags || []);
+    const cleanup = extractCleanupFlags(feature.tags || []);
     const screenshotOnFailure = hasScreenshotOnFailure(feature.tags || []);
 
     // Use adapter to render the complete test file structure
@@ -439,12 +499,27 @@ export class CodeGenerator {
       runtimeData: this.options.runtimeData,
       screenName: isFlowFeature ? `flows/${effectiveScreenName}` : effectiveScreenName,
       featureFileName: featureName,
+      isParallel,
+      cleanup,
+      backgroundSteps,
       scenarios: needsGrouping ? [] : scenarios,
       authGroups: needsGrouping ? authGroups : undefined,
       singleAuthRole,
     });
   }
 
+  private async generateBackgroundSteps(background: ParsedScenario): Promise<Array<{ comment?: string; code: string }>> {
+    const steps: Array<{ comment?: string; code: string }> = [];
+    for (const step of background.steps) {
+      const mapped = await Promise.resolve(this.stepMapper.mapStep(step));
+      steps.push({
+        comment: mapped.comment,
+        code: this.indentCode(mapped.code, 4),
+      });
+    }
+    return steps;
+  }
+
   private async generateBeforeEach(background: ParsedScenario): Promise<string> {
     // Map all steps
     const steps: Array<{ comment?: string; code: string }> = [];
@@ -484,9 +559,10 @@ export class CodeGenerator {
   }
 
   private async generateScenario(
-    scenario: ParsedScenario, 
+    scenario: ParsedScenario,
     hasBackground: boolean,
-    featureTags: string[] = []
+    featureTags: string[] = [],
+    isParallel: boolean = false
   ): Promise<string> {
     // Resolve base steps and tags for @extend scenarios
     let stepsToMap = scenario.steps;
@@ -545,11 +621,16 @@ export class CodeGenerator {
       }
     }
 
+    // Extract pass-through tags (feature + scenario, excluding functional tags)
+    const tags = extractPassThroughTags(scenario.tags, featureTags);
+
     // Use adapter to render scenario
     return this.adapter.renderScenario({
       scenarioName: scenario.name,
       steps,
-      authRole
+      authRole,
+      isParallel,
+      tags,
     });
   }
 

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

@@ -296,12 +296,34 @@ export const interactionPatterns: StepPattern[] = [
     matcher: (step: ParsedStep) =>
       (step.text.includes('wait for') || step.text.includes('waits for')) && step.elementType === 'page',
     resolver: (step, context) => {
-      const path = step.featurePath || '/';
-      const pathRegex = path.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+      let path = step.featurePath || '/';
+
+      if (step.selectorRef) {
+        try {
+          const resolved = context.selectorResolver.resolveSelector(
+            step.selectorRef, context.featureName, step.elementType, step.nth
+          );
+          path = resolved.value || path;
+        } catch (error) {
+          // fallback to featurePath
+        }
+      }
+
+      const isAbsoluteUrl = /^https?:\/\//.test(path);
+      let pathRegex: string;
+      if (isAbsoluteUrl) {
+        const url = new URL(path);
+        const hostEscaped = url.hostname.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+        const pathEscaped = url.pathname !== '/' ? url.pathname.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&') : '';
+        pathRegex = hostEscaped + pathEscaped;
+      } else {
+        pathRegex = path.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+      }
+
       return {
         templateName: 'wait-for-page',
         data: { pathRegex },
-        comment: `Wait for page`,
+        comment: step.selectorRef ? `Wait for ${step.selectorRef} page` : `Wait for page`,
       };
     },
     priority: 9,

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

@@ -26,10 +26,11 @@ export const navigationPatterns: StepPattern[] = [
       }
 
       const finalPath = resolvePathVariables(path, context.scenarioSteps || []);
+      const isAbsoluteUrl = /^https?:\/\//.test(finalPath);
 
       return {
         templateName: 'navigation',
-        data: { baseURL: context.baseURL, path: finalPath },
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath },
         comment: step.selectorRef ? `Open ${step.selectorRef} page` : `Navigate to page`,
       };
     },
@@ -52,10 +53,12 @@ export const navigationPatterns: StepPattern[] = [
       });
       const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
       const pathCode = getPathCode(resolvedPath);
+      const cleanPath = pathCode.replace(/^['`]|['`]$/g, '');
+      const isAbsoluteUrl = /^https?:\/\//.test(cleanPath);
 
       return {
         templateName: 'navigation',
-        data: { baseURL: context.baseURL, path: pathCode.replace(/^['`]|['`]$/g, '') },
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: cleanPath },
         comment: `Open ${pageName}`,
       };
     },
@@ -75,10 +78,12 @@ export const navigationPatterns: StepPattern[] = [
       });
       const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
       const pathCode = getPathCode(resolvedPath);
+      const cleanPath = pathCode.replace(/^['`]|['`]$/g, '');
+      const isAbsoluteUrl = /^https?:\/\//.test(cleanPath);
 
       return {
         templateName: 'navigation',
-        data: { baseURL: context.baseURL, path: pathCode.replace(/^['`]|['`]$/g, '') },
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: cleanPath },
         comment: `Navigate to ${route}`,
       };
     },

package/src/generators/test-generator/template-engine.ts

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..' });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport });
   }
 
   renderTestFile(data: {
@@ -246,6 +246,9 @@ export class TemplateEngine {
     runtimeData?: boolean;
     screenName?: string;
     featureFileName?: string;
+    isParallel?: boolean;
+    cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
+    backgroundSteps?: Array<{ comment?: string; code: string }>;
     scenarios: string[];
     authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
     singleAuthRole?: string;

package/src/orchestrator/screen-manager.ts

@@ -358,9 +358,11 @@ export class ScreenManager {
   So that I can accomplish my tasks
   Path: ${featurePath}
 
+  Background:
+    Given User is on [${screenName}] page
+
   @high
   Scenario: Sample scenario for ${options.name}
-    Given User is on [${screenName}] page
     When User click [element] button
     Then User see [result] text with {{success}}
 `;

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

@@ -120,6 +120,32 @@ Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label
 - Same label, nth occurrence → add `--N` suffix
 - Target Name > 30 chars → shorten to 1–3 meaningful words
 
+## Dynamic Variables (test-data YAML)
+
+Use `{{$var}}` in test-data YAML for values that must be unique per test run. Resolved at **runtime** by `TestDataLoader` — the compiler passes them through unchanged.
+
+| Variable | Example | Output |
+|---|---|---|
+| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000"` |
+| `{{$uuid}}` | `"{{$uuid}}"` | `"a1b2c3d4-..."` |
+| `{{$random:min:max}}` | `"{{$random:1:100}}"` | `"42"` |
+| `{{$date}}` | `"{{$date}}"` | `"2026-04-24"` |
+| `{{$datetime}}` | `"{{$datetime}}"` | `"2026-04-24T10:30:00.000Z"` |
+
+**Rules:**
+- `$timestamp` and `$uuid` → same value across all keys in one `load()` call (stable within a test file)
+- `$random` → unique per occurrence (each key gets a different random)
+- Resolved once at load time → every `get()` returns the same resolved value
+- Use for CRUD flows to avoid data collision between parallel runs
+
+```yaml
+# test-data/crud-award.yaml
+award:
+  name: "Award-{{$timestamp}}"
+  email: "test+{{$uuid}}@example.com"
+  score: "{{$random:1:100}}"
+```
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -138,27 +164,60 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 ## Tags
 
+### Functional tags (affect code generation)
+
 | Tag | Effect |
 |---|---|
-| `@auto` | Standard scenario, ready for automation |
 | `@manual` | Skip in generation |
-| `@smoke` / `@regression` | Test suite grouping |
-| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
-| `@high` | Priority: major feature broken (required validation, key business rules) |
-| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
-| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
 | `@auth:role` | Use auth storage state for role |
 | `@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) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (cleanupPage) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (cleanupPage) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
 | `@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()` |
+| `@flow` | Mark feature as E2E flow (cross-screen testing) |
+
+### Pass-through tags (filter at runtime via Playwright --grep)
+
+Any tag not listed above passes through to Playwright `{ tag: [...] }`. Feature-level tags inherit to all scenarios.
+
+| Tag | Purpose |
+|---|---|
+| `@smoke` | Quick sanity check — run after every deploy |
+| `@regression` | Full test suite — run nightly or before release |
+| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
+| `@high` | Priority: major feature broken (required validation, key business rules) |
+| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
+| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
+| `@auto` | Standard scenario, ready for automation |
+| Any custom | e.g., `@sprint-42`, `@team-payment` — any tag works |
+
+**Run filtered:**
+```bash
+npx playwright test --grep "@smoke"          # only smoke tests
+npx playwright test --grep "@critical"       # only critical priority
+npx playwright test --grep "@smoke|@critical" # smoke OR critical
+```
+
+### Serial vs Parallel (test execution mode)
+
+**Default: serial** — `test.describe.serial()` with shared page. Background runs once in `beforeAll`. Fail → skip remaining.
+
+**`@parallel` opt-out** — `test.describe()` with fresh page per test. Background runs as `beforeEach`. Use when scenarios are truly independent (validation rules, permission tests).
+
+| Mode | Generated | Page | Background | On fail |
+|---|---|---|---|---|
+| Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
+| `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
+
+**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
 
 ### `@flow` tag (E2E cross-screen testing)
 
@@ -172,6 +231,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Selectors | `[Element]` → own YAML | `[Screen:Element]` → own YAML (namespaced) |
 | Test data | `{{variable}}` | `{{phase.variable}}` (namespaced by phase) |
 | Tag | `@auto` / `@smoke` etc. | `@flow` (required at feature level) |
+| Multi-domain | N/A | Absolute URL in selector `path:` skips baseURL |
 
 **Selector namespace format:** `[Screen:Element]` where colon separates screen prefix from element name. The YAML key is `"screen:element"` (quoted, lowercase).
 

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

@@ -161,6 +161,29 @@ Scenario: Reset filters to default
 
 For one-time setup/teardown. Most screens don't need these.
 
+### `@parallel` — when tests need independent browser state
+
+Add `@parallel` at feature level when:
+
+1. **Multiple auth groups** (required) — e.g., `@auth:user` + `@no-auth` scenarios. Serial mode uses one shared context and cannot mix auth roles. Compiler will error without this tag.
+2. **Validation-heavy features** (recommended) — each scenario fills forms with different invalid data and needs a clean form. Serial shared page keeps previous test's input.
+
+Serial (default) is best for: CRUD flows, sequential user journeys, UI checks on the same page.
+
+```gherkin
+@parallel @auth:user
+@cleanup:forms
+Feature: kudos Screen
+
+  @critical
+  Scenario: Send kudos
+    ...
+
+  @critical @no-auth
+  Scenario: Unauthenticated user is redirected
+    ...
+```
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`

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

@@ -120,6 +120,32 @@ Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label
 - Same label, nth occurrence → add `--N` suffix
 - Target Name > 30 chars → shorten to 1–3 meaningful words
 
+## Dynamic Variables (test-data YAML)
+
+Use `{{$var}}` in test-data YAML for values that must be unique per test run. Resolved at **runtime** by `TestDataLoader` — the compiler passes them through unchanged.
+
+| Variable | Example | Output |
+|---|---|---|
+| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000"` |
+| `{{$uuid}}` | `"{{$uuid}}"` | `"a1b2c3d4-..."` |
+| `{{$random:min:max}}` | `"{{$random:1:100}}"` | `"42"` |
+| `{{$date}}` | `"{{$date}}"` | `"2026-04-24"` |
+| `{{$datetime}}` | `"{{$datetime}}"` | `"2026-04-24T10:30:00.000Z"` |
+
+**Rules:**
+- `$timestamp` and `$uuid` → same value across all keys in one `load()` call (stable within a test file)
+- `$random` → unique per occurrence (each key gets a different random)
+- Resolved once at load time → every `get()` returns the same resolved value
+- Use for CRUD flows to avoid data collision between parallel runs
+
+```yaml
+# test-data/crud-award.yaml
+award:
+  name: "Award-{{$timestamp}}"
+  email: "test+{{$uuid}}@example.com"
+  score: "{{$random:1:100}}"
+```
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -138,27 +164,60 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 ## Tags
 
+### Functional tags (affect code generation)
+
 | Tag | Effect |
 |---|---|
-| `@auto` | Standard scenario, ready for automation |
 | `@manual` | Skip in generation |
-| `@smoke` / `@regression` | Test suite grouping |
-| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
-| `@high` | Priority: major feature broken (required validation, key business rules) |
-| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
-| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
 | `@auth:role` | Use auth storage state for role |
 | `@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) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (cleanupPage) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (cleanupPage) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
 | `@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()` |
+| `@flow` | Mark feature as E2E flow (cross-screen testing) |
+
+### Pass-through tags (filter at runtime via Playwright --grep)
+
+Any tag not listed above passes through to Playwright `{ tag: [...] }`. Feature-level tags inherit to all scenarios.
+
+| Tag | Purpose |
+|---|---|
+| `@smoke` | Quick sanity check — run after every deploy |
+| `@regression` | Full test suite — run nightly or before release |
+| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
+| `@high` | Priority: major feature broken (required validation, key business rules) |
+| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
+| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
+| `@auto` | Standard scenario, ready for automation |
+| Any custom | e.g., `@sprint-42`, `@team-payment` — any tag works |
+
+**Run filtered:**
+```bash
+npx playwright test --grep "@smoke"          # only smoke tests
+npx playwright test --grep "@critical"       # only critical priority
+npx playwright test --grep "@smoke|@critical" # smoke OR critical
+```
+
+### Serial vs Parallel (test execution mode)
+
+**Default: serial** — `test.describe.serial()` with shared page. Background runs once in `beforeAll`. Fail → skip remaining.
+
+**`@parallel` opt-out** — `test.describe()` with fresh page per test. Background runs as `beforeEach`. Use when scenarios are truly independent (validation rules, permission tests).
+
+| Mode | Generated | Page | Background | On fail |
+|---|---|---|---|---|
+| Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
+| `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
+
+**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
 
 ### `@flow` tag (E2E cross-screen testing)
 
@@ -172,6 +231,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Selectors | `[Element]` → own YAML | `[Screen:Element]` → own YAML (namespaced) |
 | Test data | `{{variable}}` | `{{phase.variable}}` (namespaced by phase) |
 | Tag | `@auto` / `@smoke` etc. | `@flow` (required at feature level) |
+| Multi-domain | N/A | Absolute URL in selector `path:` skips baseURL |
 
 **Selector namespace format:** `[Screen:Element]` where colon separates screen prefix from element name. The YAML key is `"screen:element"` (quoted, lowercase).
 

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

@@ -174,6 +174,29 @@ Scenario: Reset filters to default
 
 For one-time setup/teardown. Most screens don't need these.
 
+### `@parallel` — when tests need independent browser state
+
+Add `@parallel` at feature level when:
+
+1. **Multiple auth groups** (required) — e.g., `@auth:user` + `@no-auth` scenarios. Serial mode uses one shared context and cannot mix auth roles. Compiler will error without this tag.
+2. **Validation-heavy features** (recommended) — each scenario fills forms with different invalid data and needs a clean form. Serial shared page keeps previous test's input.
+
+Serial (default) is best for: CRUD flows, sequential user journeys, UI checks on the same page.
+
+```gherkin
+@parallel @auth:user
+@cleanup:forms
+Feature: kudos Screen
+
+  @critical
+  Scenario: Send kudos
+    ...
+
+  @critical @no-auth
+  Scenario: Unauthenticated user is redirected
+    ...
+```
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`

package/src/orchestrator/templates/playwright.config.ts

@@ -28,7 +28,14 @@ export default defineConfig({
   /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
   reporter: [
     ['html'],
-    ['json', { outputFile: process.env.PLAYWRIGHT_JSON_OUTPUT_NAME || 'test-results/results.json' }],
+    [
+      'json',
+      {
+        outputFile:
+          process.env.PLAYWRIGHT_JSON_OUTPUT_NAME ||
+          'test-results/results.json',
+      },
+    ],
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
@@ -40,6 +47,9 @@ export default defineConfig({
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
+
+    /* Capture screenshot after each test failure. */
+    screenshot: 'only-on-failure',
   },
 
   /* Configure projects for major browsers */