@sun-asterisk/sungen 3.2.31 → 3.2.33

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/visible-filtered-assertion.hbs

@@ -7,7 +7,7 @@
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
   const __norm = (s: string) => s.replace(/\s+/g, ' ').trim().toLowerCase();
-  const __items = await $$({{> appium-selector-expr}});
+  const __items = {{> await-elements mustExist=true}};
   let __found = false;
   for (const __el of __items) {
     const __sources = driver.isIOS

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,13 +1,17 @@
 {{!-- Role variable, visible (mobile best-effort): ARIA role has no native-mobile analog — reuse
       the role→accessibility-id mapping in appium-selector.hbs (`~name`) when a static name
       exists; the resolver already folds dataValue into name when there is none, so this is only
-      the fallback for a caller that omits both. --}}
+      the fallback for a caller that omits both.
+
+      SCOPE (#747): an `in [Parent] <type>` clause chains this under the parent element. Both
+      branches locate by accessibility id / predicate, neither of which carries the absolute-xpath
+      trap the label-value twin has to work around. --}}
 {{#if name}}
-await expect($('~{{escapeQuotes name}}')).toBeDisplayed();
+await expect({{#if parentLocator}}{{parentLocator}}.$('~{{escapeQuotes name}}'){{else}}$('~{{escapeQuotes name}}'){{/if}}).toBeDisplayed();
 {{else}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
   const __sel = driver.isIOS ? `-ios predicate string:label == "${__expected}" OR value == "${__expected}"` : `android=new UiSelector().text("${__expected}")`;
-  await expect($(__sel)).toBeDisplayed();
+  await expect({{#if parentLocator}}{{parentLocator}}.$(__sel){{else}}$(__sel){{/if}}).toBeDisplayed();
 }
 {{/if}}

package/src/generators/test-generator/adapters/appium/templates/steps/partials/await-elements.hbs

@@ -0,0 +1,12 @@
+{{~!--
+  The settled read behind every collection assertion on this adapter. `await $$(sel)` is a one-shot
+  read, so a loop over its result asserts nothing at all when the list has not painted yet — the
+  false-green class #672 closed on the Playwright side and left here.
+
+  Hash params:
+    mustExist   the assertion is meaningless over an empty set (positive assertions). Omitted means
+                emptiness is a legitimate verdict (the negated `is hidden` forms).
+    useRoleName the two role-variable templates search by accessibility id built from `name:`
+                rather than through the selector entry.
+--~}}
+await __settleElements({{#if useRoleName}}'~{{escapeQuotes name}}'{{else}}{{> appium-selector-expr}}{{/if}}, {{#if mustExist}}true{{else}}false{{/if}}, '{{escapeQuotes selectorRef}}')

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -119,6 +119,32 @@ async function __ensureVisible(selector: string): Promise<WebdriverIO.Element> {
   return $(selector);
 }
 
+// Read a live element ARRAY after giving the tree a chance to render.
+//
+// `await $$(sel)` is a ONE-SHOT read — unlike a Playwright Locator it does not re-query, so an
+// assertion that loops over the result silently asserts NOTHING when the list has not painted yet:
+// zero matches, zero iterations, green. #672 fixed that class on the Playwright side and left the
+// appium adapter untouched, so every collection assertion here still raced the first render.
+//
+// `mustExist` says which verdict emptiness is. A positive assertion ("all of them contain X",
+// "every match is disabled") is meaningless over an empty set, so it waits the full budget and
+// then fails naming the reference. A negated one ("none of them is displayed") is legitimately
+// satisfied by absence, so it only waits long enough to outlast a render race and then proceeds
+// with whatever it found — waiting the full budget there would add 15s to every correct `is
+// hidden` step, which is a worse trade than the race it would close.
+async function __settleElements(
+  selector: string, mustExist: boolean, ref: string,
+): Promise<WebdriverIO.Element[]> {
+  try {
+    await (await $(selector)).waitForExist({ timeout: mustExist ? 15000 : 3000 });
+  } catch {
+    if (mustExist) {
+      throw new Error(`[sungen] Expected at least one ${ref ? `[${ref}]` : `element matching ${selector}`} — none appeared within 15s`);
+    }
+  }
+  return $$(selector);
+}
+
 // Visibility oracle for simple-case `see [X]` assertions. Android: WDIO's toBeDisplayed()
 // (reliable on UiAutomator2). iOS: XCUITest's `visible` attribute false-negatives on real,
 // on-screen elements (snapshot artifact — seen live even on a screen title every prior run
@@ -476,9 +502,36 @@ describe('{{featureName}}', () => {
   // lose the escalation between them — SG-W024 already reports that shape when tiers are involved.)
   let __escalateAfter: string | null = null;
 
+  // `@known-defect` marks a scenario that is EXPECTED to be red — it asserts a live defect. The
+  // scaffolded /sungen:run-test command tells authors exactly that ("expected-red scenarios stay red;
+  // never 'fix' them"), so the ladder honours it here: such a failure is the suite working as
+  // designed, not evidence of leftover state. Arming escalation off it would make the NEXT scenario
+  // pay a harder reset for nothing — on every run, forever, because the defect is known.
+  //
+  // Read off the TITLE because `@known-defect` is a pass-through tag: appium appends it there as the
+  // `[@a @b]` suffix (which is what keeps it greppable via `--grep`), and that is how the field
+  // report shows it. Anchored to that trailing group, so a scenario merely NAMED `… known-defect …`
+  // cannot exempt itself — the same reason __tierFor refuses to strip a trailing `[Selector]` ref.
+  //
+  // Matched as a whole TAG TOKEN, never as a substring. `@known-defect-list` is a DIFFERENT tag, and
+  // reading it as this one would silently stop the next scenario's real dirty-state failure from
+  // getting the escalated reset it needs — with no log line at all, because "never armed" is not the
+  // "capped" path and prints nothing. The `:<ref>` parameter form is accepted because that is what
+  // the rest of the vocabulary does (`@manual:M10`, `@reset:data`).
+  //
+  // Caveat, inherited rather than introduced: a @cases scenario builds its title at runtime as
+  // `name — <row label>`, so a row LABEL that itself ends in `[@…]` would be read as the tag group.
+  // Same trailing-bracket ambiguity __tierFor accepts for a `[Selector]` ref.
+  function __isExpectedFail(title: string): boolean {
+    const tagGroup = title.match(/ \[@[^\]]*\]$/);
+    if (!tagGroup) return false;
+    return tagGroup[0].slice(2, -1).split(/\s+/)
+      .some((t) => t === '@known-defect' || t.startsWith('@known-defect:'));
+  }
+
   // Registered BEFORE any user @afterEach block so a throwing user hook cannot skip the bookkeeping.
   afterEach(async function () {
-    __escalateAfter = this.currentTest?.state === 'failed' ? (this.currentTest?.title ?? '') : null;
+    __escalateAfter = this.currentTest?.state === 'failed' && !__isExpectedFail(this.currentTest?.title ?? '') ? (this.currentTest?.title ?? '') : null;
   });
 
 {{#if scenarioResetTiers}}
@@ -557,9 +610,31 @@ describe('{{featureName}}', () => {
     await driver.execute('mobile: clearApp', { appId: pkg });
   }
 
-  async function __reinstallApp(pkg: string): Promise<void> {
+  /** The app's build file, when the session was given one. Absent when the app was attached BY PACKAGE. */
+  function __appBuildPath(): string | undefined {
     const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
-    const appPath = caps['appium:app'] || caps['app'];
+    return caps['appium:app'] || caps['app'];
+  }
+
+  /**
+   * The strongest tier THIS SESSION can actually carry out.
+   *
+   * Reinstalling needs the app's build file, and `data` on iOS IS a reinstall (no `mobile: clearApp`
+   * outside UiAutomator2). Attaching the app by package — the common local setup — leaves no build
+   * file, so those tiers cannot run at all.
+   *
+   * This exists so ESCALATION can cap itself. Escalation is a recovery the runner CHOSE; nothing
+   * asked for it. Escalating into a tier that throws turns one failed scenario into a dead spec file,
+   * because the throw lands in `beforeEach` and mocha then skips every remaining test in the file.
+   * A DECLARED tier is never capped — that is an unmet contract and must still throw by name.
+   */
+  function __performableTier(): string {
+    if (__appBuildPath()) return 'full';
+    return driver.isIOS ? 'soft' : 'data';
+  }
+
+  async function __reinstallApp(pkg: string): Promise<void> {
+    const appPath = __appBuildPath();
     if (!appPath) {
       throw new Error(
         `reset tier needs the app's build file to reinstall — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present, or drop to @reset:soft.`,
@@ -611,9 +686,24 @@ describe('{{featureName}}', () => {
     // Same title ⟹ this is a retry of the scenario that just failed: keep its declared tier so a real
     // failure fails both attempts (see __escalateAfter above).
     const __escalate = __escalateAfter !== null && __escalateAfter !== (this.currentTest?.title ?? '');
-    const __tier = __escalate ? __ESCALATE[__base] : __base;
+    // Escalation caps at what this session can perform, with the DECLARED tier as the FLOOR.
+    // The cap stops a tier NOBODY ASKED FOR from throwing in this hook and taking the rest of the
+    // spec file with it. The floor stops the cap from silently WEAKENING what the feature declared:
+    // a declared tier this session cannot perform still reaches __resetApp and still throws by name,
+    // because that one IS an unmet contract.
+    const __want = __escalate ? __ESCALATE[__base] : __base;
+    const __tier = __escalate
+      ? __TIER_ORDER[Math.max(
+          __TIER_ORDER.indexOf(__base),
+          Math.min(__TIER_ORDER.indexOf(__want), __TIER_ORDER.indexOf(__performableTier())),
+        )]
+      : __want;
     if (__tier !== __base) {
       console.log(`  \u2191 reset escalated ${__base} \u2192 ${__tier} (previous scenario failed: "${__escalateAfter}")`);
+    } else if (__want !== __base) {
+      // Said per occurrence, not once per run: this names the scenario that did NOT get the stronger
+      // reset it was owed, which is a fact about THIS scenario, not just about the session.
+      console.warn(`  ! reset could not escalate ${__base} \u2192 ${__want} — this session has no app build file to reinstall from (the app was attached by package). Staying at ${__base}; set APP_APK (Android) / IOS_APP (iOS) to enable the stronger reset.`);
     }
     await __resetApp(__tier);
 {{#if backgroundSteps}}

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/capture-variable.hbs

@@ -1 +1,7 @@
-testData.set('{{varName}}', ((await {{> locator}}.{{capture}}()) ?? '').trim());
+{{!-- `.first()` unless the entry pinned an index. A capture reads ONE element; without it,
+      Playwright's strict mode turned any selector matching more than one node into a hard failure
+      naming the count rather than the step — and the documented workaround was to add `nth: 0`,
+      i.e. to ask for exactly this. `{{> locator}}` already appends `.nth(n)` when `nth:` is
+      declared, so the two never stack. The compiler warns (SG-W036) when the selector is a SHAPE
+      that routinely matches a list, so "the first one" stays a decision rather than an accident. --}}
+testData.set('{{varName}}', ((await {{> locator}}{{#unless (isDefined nth)}}.first(){{/unless}}.{{capture}}()) ?? '').trim());

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

@@ -1 +1,7 @@
-await expect(page.getByText(/{{#if label}}{{escapeRegex label}}\s*{{else}}(?:^|\s){{/if}}{{escapeRegex dataValue}}$/)).toBeVisible();
+{{!-- Caption+value read: the ref names on-screen TEXT ("学科 -"), not an element, so the locator is
+      built inline from the caption rather than through the `locator` partial. That is why the scope
+      clause needs its own slot here — the partial's `parentLocator` handling never runs (#747).
+      Unscoped, `… in [Education Card 6] card` compiled away to nothing: on a screen repeating ten
+      学歴・職歴 cards the assertion strict-mode-failed where the caption repeats, and where it
+      happened to be unique elsewhere it passed having read a DIFFERENT card than the sentence names. --}}
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByText(/{{#if label}}{{escapeRegex label}}\s*{{else}}(?:^|\s){{/if}}{{escapeRegex dataValue}}$/)).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/row-scoped-column-assertion.hbs

@@ -1 +1,23 @@
-{{!-- Column assertion scoped to the current row (`tableRow`, bound by the row-in-table entry step that ran before this one). columnIndex uses `isDefined` rather than a bare truthy check: column 0 is a valid index. --}}{{#if (isDefined columnIndex)}}await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth({{columnIndex}})).toHaveText('{{escapeQuotes cellValue}}');{{else if isGiven}}await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true }).waitFor();{{else}}await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true })).toBeVisible();{{/if}}
+{{!-- Column assertion scoped to the current row (`tableRow`, bound by the row-in-table entry step
+      that ran before this one).
+
+      `cellLocator` is the DECLARED cell — `columns.<col>.elements.cell` on the table entry, already
+      rendered against `tableRow`. It comes first because it is the only branch that works on a row
+      built from <div>s: those rows carry no ARIA `cell` role, so both branches below match zero
+      elements there, and `columns.<col>.index` cannot help — it indexes that same empty set. The
+      compiler warns (SG-W034) when a `rows:` shape is declared and no cell is.
+
+      columnIndex uses `isDefined` rather than a bare truthy check: column 0 is a valid index.
+
+      includeHidden + visible filter: when a modal (e.g. Radix Dialog) is open the background gets
+      aria-hidden="true", which empties plain getByRole() even though the cells are still rendered
+      — measure what the user SEES, not the a11y tree. --}}
+{{~#if cellLocator~}}
+{{#if isGiven}}await {{cellLocator}}.filter({ hasText: '{{escapeQuotes cellValue}}' }).waitFor();{{else}}await expect({{cellLocator}}).toHaveText('{{escapeQuotes cellValue}}');{{/if}}
+{{~else if (isDefined columnIndex)~}}
+await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth({{columnIndex}})).toHaveText('{{escapeQuotes cellValue}}');
+{{~else if isGiven~}}
+await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true }).waitFor();
+{{~else~}}
+await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true })).toBeVisible();
+{{~/if~}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,9 +1,13 @@
+{{!-- `getByRole` is built inline from role/name rather than through the `locator` partial, so the
+      scope clause needs its own slot here exactly as in label-value-assertion — the label branch's
+      twin (#747). `see [Logo] image with {{alt}} in [Product Card 3] card` searched every card on
+      the page before this. --}}
 {{#if name}}
 {{#if dataValue}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
 {{else}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{> locator-nth}}).toBeVisible();
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{> locator-nth}}).toBeVisible();
 {{/if}}
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
-{{/if}}
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
+{{/if}}

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

@@ -5,8 +5,8 @@
   {{~#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('{{escapeQuotes value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
-  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
+  {{~#case 'id'}}locator('{{escapeQuotes (cssIdSelector locator value)}}'){{/case~}}
+  {{~#default}}locator('{{#if locator}}{{escapeQuotes locator}}{{else}}{{escapeQuotes value}}{{/if}}'){{/default~}}
 {{~/switch}}{{else~}}
 {{#if scope}}{{#if (eq scope "dialog")}}{{pageRoot}}.{{else}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{/if}}{{#switch strategy~}}
   {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
@@ -15,8 +15,8 @@
   {{~#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('{{escapeQuotes value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
-  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
+  {{~#case 'id'}}locator('{{escapeQuotes (cssIdSelector locator value)}}'){{/case~}}
+  {{~#default}}locator('{{#if locator}}{{escapeQuotes locator}}{{else}}{{escapeQuotes value}}{{/if}}'){{/default~}}
 {{~/switch}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}

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

@@ -1 +1 @@
-page.locator('{{escapeQuotes selector}}')
+{{pageRoot}}.locator('{{#if locator}}{{escapeQuotes locator}}{{else}}{{escapeQuotes value}}{{/if}}')

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

@@ -1 +1 @@
-page.locator('{{escapeQuotes selector}}')
+{{pageRoot}}.locator('{{escapeQuotes (cssIdSelector locator value)}}')

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

@@ -5,8 +5,8 @@
   {{~#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('{{escapeQuotes value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
-  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
+  {{~#case 'id'}}locator('{{escapeQuotes (cssIdSelector locator value)}}'){{/case~}}
+  {{~#default}}locator('{{#if locator}}{{escapeQuotes locator}}{{else}}{{escapeQuotes value}}{{/if}}'){{/default~}}
 {{~/switch}}{{> locator-nth}}{{else~}}
 {{#if scope}}{{#if (eq scope "dialog")}}{{pageRoot}}.{{else}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{/if}}{{#switch strategy~}}
   {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
@@ -15,8 +15,8 @@
   {{~#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('{{escapeQuotes value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
-  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
+  {{~#case 'id'}}locator('{{escapeQuotes (cssIdSelector locator value)}}'){{/case~}}
+  {{~#default}}locator('{{#if locator}}{{escapeQuotes locator}}{{else}}{{escapeQuotes value}}{{/if}}'){{/default~}}
 {{~/switch}}{{> locator-nth}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}

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

@@ -15,5 +15,20 @@
 
       `expectPage`, not a bare `toHaveURL`: a polling URL assertion passes on the first transient
       match, before a route guard has bounced the user away (#662). The helper arrives, lets the
-      page settle, holds, and re-asserts — read specs/url-assert.ts. --}}
-await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });
+      page settle, holds, and re-asserts — read specs/url-assert.ts.
+
+      `hostname` rides separately and only for an absolute page value, exactly as in the
+      `wait-for-page` twin: it is read off `u.hostname`, which never appears in `u.pathname`, so
+      one concatenated regex cannot carry both. Without it a page declared as
+      `https://admin.example.com/jobs` asserted the PATH on any host, and the public site's /jobs
+      satisfied it.
+
+      `ignoreQuery` comes from the page ENTRY's `query: any`, not from the step, because it is a fact
+      about the page rather than about one assertion (#748). It relaxes only the bare-page rule; the
+      declared-value half below is untouched, so the two compose rather than override each other.
+
+      The declared-value half is gated on `dataRef`, not on `query`. The step wrote `with {{v}}`
+      either way; gating on the resolved VALUE meant an empty test-data entry silently dropped the
+      whole check and fell back to the bare-page rule, which is the one case specs/url-assert.ts
+      exists to throw on. --}}
+await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if hostRegex}}, hostname: /^{{hostRegex}}$/{{/if}}{{#if ignoreQuery}}, ignoreQuery: true{{/if}}{{#if dataRef}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });

package/src/generators/test-generator/adapters/playwright/templates/test-file.hbs

@@ -49,6 +49,20 @@ test.describe('{{featureName}}', () => {
 {{#each scenarios}}
 {{indent this 2}}
 
+{{/each}}
+  });
+
+{{else if noAuth}}
+{{!-- @no-auth demands an EMPTY session (#735). Leaving the group bare inherits whatever
+     playwright.config.ts set through `use.storageState`, so "an anonymous visitor is redirected to
+     sign-in" ran signed in and passed for the wrong reason. Omitting storageState inherits it —
+     an inline empty state is the only way to say "no session". --}}
+  test.describe('no-auth', () => {
+    test.use({ storageState: { cookies: [], origins: [] } });
+
+{{#each scenarios}}
+{{indent this 2}}
+
 {{/each}}
   });
 

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

@@ -167,23 +167,51 @@ function extractAuthRole(tags: string[]): string | undefined {
  * Precedence: Scenario > Feature > None
  */
 function getEffectiveAuthRole(
-  scenarioTags: string[], 
+  scenarioTags: string[],
   featureTags: string[]
 ): string | undefined {
   // Check for explicit @no-auth override
   if (scenarioTags.some(tag => tag === '@no-auth')) {
     return undefined;
   }
-  
+
   // Scenario-level takes precedence
   const scenarioRole = extractAuthRole(scenarioTags);
   if (scenarioRole) return scenarioRole;
-  
+
   // Fall back to feature-level
   const featureRole = extractAuthRole(featureTags);
   return featureRole;
 }
 
+/**
+ * The three auth states a scenario can be in — they are NOT two (#735).
+ *
+ * `@no-auth` and "no auth tag at all" both leave `getEffectiveAuthRole` undefined, but they mean
+ * opposite things: the first demands an EMPTY session, the second inherits whatever
+ * `playwright.config.ts` set via `use.storageState`. Collapsing them put both in one group, so a
+ * scenario written to prove "an anonymous visitor is bounced to sign-in" ran signed in and passed
+ * for the wrong reason — while the exported test case still printed "Not authenticated".
+ *
+ * Returned as a flag beside the role rather than a tagged union so every existing `authRole` reader
+ * keeps working unchanged; only the grouping and the template consult `noAuth`.
+ */
+function getAuthMode(
+  scenarioTags: string[],
+  featureTags: string[],
+): { noAuth: boolean; authRole: string | undefined } {
+  if (scenarioTags.some(tag => tag === '@no-auth')) {
+    return { noAuth: true, authRole: undefined };
+  }
+  return { noAuth: false, authRole: getEffectiveAuthRole(scenarioTags, featureTags) };
+}
+
+/**
+ * Grouping key for the anonymous bucket. A literal that no `@auth:<role>` can produce, so an
+ * imaginative role name can never land in the same group as `@no-auth`.
+ */
+const NO_AUTH_GROUP_KEY = '\0no-auth';
+
 
 /**
  * True when the scenario has at least one step in the Then bucket —
@@ -238,6 +266,56 @@ function warnMultipleAuthTags(tags: string[], context: string): void {
   }
 }
 
+/**
+ * Drop the YAML comment from ONE line: a `#` at line start or preceded by whitespace,
+ * and not inside a quoted scalar. Line-level only — see `yamlWithoutComments` for the
+ * block-scalar case, which this function cannot see from a single line.
+ */
+function stripYamlComment(line: string): string {
+  let quote: string | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (quote === '"' && c === '\\') { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+/**
+ * The YAML text a `${QA_*}` scan may look at: comments removed, block scalars kept whole.
+ *
+ * SG-W009's reference scan used to run over the whole raw file, so a `${QA_*}` that only ever
+ * appeared in a `#` comment counted as a live reference — including the one sungen's own
+ * scaffolded "HOW TO FILL VALUES" block writes into every test-data file. The declared side has
+ * always been line-wise; this brings the reference side to the same footing.
+ *
+ * Inside a `|`/`>` block scalar every character is literal content, `#` included, so those lines
+ * pass through untouched. Stripping them would send the check the other way — a real, undeclared
+ * `${QA_*}` written after a `#` in a block scalar would go unreported, and the run would only fail
+ * later with "environment variable not set". A missed warning is worse than a noisy one.
+ */
+function yamlWithoutComments(text: string): string {
+  const out: string[] = [];
+  let blockIndent: number | null = null;
+  for (const line of text.split('\n')) {
+    if (blockIndent !== null) {
+      const indent = line.search(/\S/);
+      // blank lines and anything indented deeper than the key stay inside the scalar
+      if (indent === -1 || indent > blockIndent) { out.push(line); continue; }
+      blockIndent = null;
+    }
+    const block = /^(\s*)[^#\s][^:]*:\s*[|>][+-]?\d*[+-]?\s*$/.exec(line);
+    if (block) { blockIndent = block[1].length; out.push(line); continue; }
+    out.push(stripYamlComment(line));
+  }
+  return out.join('\n');
+}
+
 /**
  * Result of test generation for a single feature file
  */
@@ -699,7 +777,7 @@ export class CodeGenerator {
     // absent compiles to a skip stub instead of a real test (read once per feature).
     const enabledCaps = new Set<string>(readCapabilities(process.cwd()).enabled.map(d => d.toLowerCase()));
 
-    const renderedScenarios: Array<{ code: string; authRole?: string }> = [];
+    const renderedScenarios: Array<{ code: string; authRole?: string; noAuth?: boolean }> = [];
     for (const scenario of feature.scenarios) {
       if (isManual(scenario.tags)) {
         // SG-W008 — two-direction rule for @manual scenarios:
@@ -758,7 +836,14 @@ export class CodeGenerator {
       const reqAbsent = requiresCaps(scenario.tags).filter(c => !enabledCaps.has(c));
       if (reqAbsent.length) {
         if (this.options.verbose) console.log(`  ⏸ Pending capability (${reqAbsent.join(', ')}): ${scenario.name}`);
-        renderedScenarios.push({ code: this.generateRequiresSkipStub(scenario.name, reqAbsent), authRole: undefined });
+        // Carries its `@no-auth` tag like any other scenario so the stub lands in the group the
+        // author declared — a skipped test that reappears once the capability is enabled must not
+        // quietly change auth bucket.
+        renderedScenarios.push({
+          code: this.generateRequiresSkipStub(scenario.name, reqAbsent),
+          authRole: undefined,
+          noAuth: scenario.tags.includes('@no-auth'),
+        });
         continue;
       }
 
@@ -770,7 +855,7 @@ export class CodeGenerator {
           authFeatureTags = [...baseScenario.tags, ...authFeatureTags];
         }
       }
-      const authRole = getEffectiveAuthRole(scenario.tags, authFeatureTags);
+      const { authRole, noAuth } = getAuthMode(scenario.tags, authFeatureTags);
 
       const code = await this.generateScenario(
         scenario,
@@ -778,15 +863,16 @@ export class CodeGenerator {
         feature.tags || [],
         isParallel
       );
-      renderedScenarios.push({ code, authRole });
+      renderedScenarios.push({ code, authRole, noAuth });
     }
 
     // Group scenarios by auth role for nested test.describe blocks
-    // This ensures test.use({ storageState }) only applies to its group
+    // This ensures test.use({ storageState }) only applies to its group. `@no-auth` gets its OWN
+    // bucket (#735) — it is a demand for an empty session, not the absence of a demand.
     const authGroupMap = new Map<string, string[]>();
     const groupOrder: string[] = [];
-    for (const { code, authRole } of renderedScenarios) {
-      const key = authRole || '';
+    for (const { code, authRole, noAuth } of renderedScenarios) {
+      const key = noAuth ? NO_AUTH_GROUP_KEY : (authRole || '');
       if (!authGroupMap.has(key)) {
         authGroupMap.set(key, []);
         groupOrder.push(key);
@@ -795,7 +881,8 @@ export class CodeGenerator {
     }
 
     const authGroups = groupOrder.map(key => ({
-      authRole: key || undefined,
+      authRole: key === NO_AUTH_GROUP_KEY ? undefined : (key || undefined),
+      noAuth: key === NO_AUTH_GROUP_KEY,
       scenarios: authGroupMap.get(key)!,
     }));
 
@@ -804,6 +891,15 @@ export class CodeGenerator {
     // - Multiple groups: nested describes per auth role
     const needsGrouping = authGroups.length > 1;
 
+    // Rendering the per-group blocks is a SEPARATE question from the guards below (#735). A lone
+    // `@no-auth` group is one group — `needsGrouping` is false — yet it still has to emit its empty
+    // storageState, or an all-anonymous feature silently runs on the config's session. Keeping the
+    // guards keyed on `needsGrouping` means this never trips the appium/serial errors, which are
+    // about MIXING roles. Serial is excluded because its layout builds the context by hand with
+    // `browser.newContext()`, which never picks up `use.storageState` — already anonymous, and a
+    // `test.use` there would apply to nothing.
+    const renderAuthBlocks = needsGrouping || (isParallel && authGroups.some(g => g.noAuth));
+
     // D6 — the Appium test-file template has no per-group before-hook (only `singleAuthRole` runs
     // `__ensureAuth`); >1 auth group would render every group's scenarios with NO authentication at
     // all, silently. Mirrors the web `@parallel` guard below, but unconditional (isParallel has no
@@ -819,15 +915,18 @@ export class CodeGenerator {
 
     if (needsGrouping && !isParallel) {
       throw new Error(
-        `Feature "${feature.name}" has multiple auth groups but no @parallel tag.\n` +
+        `Feature "${feature.name}" has multiple auth groups but runs serially.\n` +
         `Serial mode uses a shared browser context — it cannot mix different auth roles.\n` +
-        `Fix: add @parallel tag to the feature.`
+        `Fix: remove the @serial tag (features are parallel by default), or split "${feature.name}" ` +
+        `into one feature file per auth role.`
       );
     }
     const scenarios = renderedScenarios.map(s => s.code);
 
-    // For single group, extract the auth role to put test.use at describe level
-    const singleAuthRole = !needsGrouping && authGroups.length === 1
+    // For single group, extract the auth role to put test.use at describe level. Keyed on
+    // `renderAuthBlocks`, not `needsGrouping`: a lone `@no-auth` group now renders its own block, so
+    // hoisting anything to the feature describe would double up. Its authRole is undefined anyway.
+    const singleAuthRole = !renderAuthBlocks && authGroups.length === 1
       ? authGroups[0].authRole
       : undefined;
 
@@ -932,8 +1031,8 @@ export class CodeGenerator {
       platform,
       cleanup,
       backgroundSteps,
-      scenarios: needsGrouping ? [] : scenarios,
-      authGroups: needsGrouping ? authGroups : undefined,
+      scenarios: renderAuthBlocks ? [] : scenarios,
+      authGroups: renderAuthBlocks ? authGroups : undefined,
       singleAuthRole,
       appPackage,
       iosBundleId,
@@ -1265,7 +1364,8 @@ export class CodeGenerator {
    * a name in the committed .env.qa.example. An undeclared ref means the test throws
    * "environment variable not set" the moment the key is used — surface it at compile
    * time instead. Only the `${QA_*}` shape is checked: any other `${...}` text is
-   * ordinary literal data by design (never resolved, never warned about).
+   * ordinary literal data by design (never resolved, never warned about). A `${QA_*}`
+   * that appears only inside a `#` comment is prose, not a reference, and is ignored.
    */
   private reportedEnvRefs = new Set<string>();
   private checkEnvSecretRefs(featureFile: string): void {
@@ -1273,7 +1373,7 @@ export class CodeGenerator {
     if (!fs.existsSync(testDataDir)) return;
     const referenced = new Set<string>();
     for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml') || x.endsWith('.yml'))) {
-      const text = fs.readFileSync(path.join(testDataDir, f), 'utf-8');
+      const text = yamlWithoutComments(fs.readFileSync(path.join(testDataDir, f), 'utf-8'));
       for (const m of text.matchAll(/\$\{(QA_[A-Z0-9_]+)\}/g)) referenced.add(m[1]);
     }
     if (!referenced.size) return;