@sun-asterisk/sungen 3.2.28 → 3.2.30

package/dist/generators/test-generator/adapters/appium/templates/before-all.hbs

@@ -1,8 +1,26 @@
   before(async () => {
+{{#if collect}}
+    // Hook checks are collected: every failed step is recorded and the hook fails ONCE with the full list
+    const __hookFailures: string[] = [];
+{{/if}}
 {{#each steps}}
 {{#if comment}}
     // {{comment}}
 {{/if}}
+{{#if wrap}}
+    try {
+{{code}}
+    } catch (e) {
+      __hookFailures.push({{label}} + ': ' + String((e as Error).message).split('\n')[0]);
+{{#if stopOnFailure}}
+      if (__hookFailures.length) throw new Error('[sungen] hook preconditions not met:\n' + __hookFailures.join('\n'));
+{{/if}}
+    }
+{{else}}
 {{code}}
+{{/if}}
 {{/each}}
+{{#if collect}}
+    if (__hookFailures.length) throw new Error('[sungen] hook preconditions not met:\n' + __hookFailures.join('\n'));
+{{/if}}
   });

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/alert-fill-action.hbs

@@ -1,2 +1,9 @@
-{{!-- Filling a native prompt is iOS-specific and app-dependent; Android rarely has fillable alerts.
-      Requested value: '{{fillValue}}'. Handle manually if your alert has a text field. --}}
+{{!-- Filling a native prompt has no Appium implementation here. This file used to be comment-ONLY,
+      which made it the one member of the web-only set that failed SILENTLY: the comment is stripped,
+      so the step emitted nothing, ran, and did nothing — a scenario could fill a prompt and pass
+      having never touched it. Every other web-only step on this adapter refuses by name, and now so
+      does this one. `alert-fill` also declares `platforms: ['web']`, so the refusal normally arrives
+      at COMPILE time (SG-W020); this body is the second line of defence for any future pattern that
+      reaches the template without declaring its platforms.
+      Requested value: '{{fillValue}}' --}}
+throw new Error("[sungen] filling a native prompt is not supported on the appium adapter. Accept or dismiss the alert instead, drive the app's own text field as a normal element, or tag this scenario @manual:M10.");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/capture-variable.hbs

@@ -6,5 +6,28 @@
   const __sources = driver.isIOS
     ? {{#if (eq capture 'inputValue')}}[await __el.getAttribute('value'), await __el.getAttribute('label')]{{else}}[await __el.getAttribute('label'), await __el.getAttribute('value')]{{/if}}
     : [await __el.getText(), await __el.getAttribute('content-desc')];
-  testData.set('{{escapeQuotes varName}}', String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim());
+  let __captured = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
+{{#if (eq capture 'inputValue')}}
+  {{!-- iOS placeholder guard. Some WebDriverAgent versions echo an empty UITextField's
+        placeholder back as its @value (the XCUITest driver documents @value as
+        "a complex attribute whose calculation algorithm depends on the actual element type"
+        and promises nothing for an empty field). Unguarded, an empty field captures its
+        PLACEHOLDER into testData under the author's variable name — and because a capture
+        feeds later steps, that corruption propagates silently instead of failing loudly.
+        Unlike the assertion path there is no expected value to gate on, so this check is
+        unconditional on iOS: one extra round-trip buys a captured value that is not a lie. --}}
+  if (driver.isIOS && __captured !== '') {
+    let __placeholder = null;
+    try { __placeholder = await __el.getAttribute('placeholderValue'); } catch { /* attribute unsupported on this node */ }
+    if (__placeholder && String(__placeholder).trim() === __captured) {
+      {{!-- Leave a breadcrumb. Unlike the assertion path — which throws at the field in
+            question — a discarded capture succeeds silently and the empty string travels to
+            whatever step later consumes it, possibly in another file. That downstream failure
+            carries nothing linking it back here, so say it out loud now. --}}
+      console.warn(`  ! [sungen] {{escapeQuotes varName}} read back as its own placeholder ("${__captured}") — captured empty instead`);
+      __captured = '';
+    }
+  }
+{{/if}}
+  testData.set('{{escapeQuotes varName}}', __captured);
 }

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/click-at-position-action.hbs

@@ -0,0 +1 @@
+throw new Error('[sungen] "click … at position/offset" is web-only — tap the control the position targets directly ("User tap [X] button"), or tag the scenario @manual');

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/click-element-with-text.hbs

@@ -1,2 +1,2 @@
 {{!-- Tap an element by its visible text / content-desc (dynamic text match). --}}
-{{#if nth}}await $$('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]')[{{nth}}].click();{{else}}await $('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]').click();{{/if}}
+{{#if (gte nth -1)}}await (await $$('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]')).at({{nth}}).click();{{else}}await $('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]').click();{{/if}}

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/double-click-action.hbs

@@ -1,6 +1,13 @@
 {{!-- Double-tap. Use the platform gesture (element.doubleClick is web-oriented). --}}
 {
   const __el = await {{> locator}};
+  // Fail loud with the REAL cause when the element never resolved. `driver.execute` does NOT do
+  // WDIO's implicit existence wait (every other action template gets that for free by going
+  // through .click()/.setValue()/expect), and the locator partial returns $(selector) even for a
+  // never-found element by design. So an undefined elementId reaches Appium, which falls through
+  // to its coordinates branch and reports "Double click offset coordinates must be provided if
+  // element is not set" — a message about offsets for what is really a not-found element (#668).
+  if (!__el.elementId) throw new Error((__el as any).error?.message || `Element not found: ${__el.selector}`);
   if (driver.isIOS) await driver.execute('mobile: doubleTap', { elementId: __el.elementId });
   else await driver.execute('mobile: doubleClickGesture', { elementId: __el.elementId });
 }

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/frame-enter-action.hbs

@@ -1,6 +1,3 @@
-{{!-- Hybrid app: switch into the webview context (mobile equivalent of entering an iframe). --}}
-{
-  const __ctxs = await driver.getContexts();
-  const __web = __ctxs.find(c => /WEBVIEW|CHROMIUM/i.test(typeof c === 'string' ? c : c.id));
-  if (__web) await driver.switchContext(typeof __web === 'string' ? __web : __web.id);
-}
+{{!-- Hybrid app: switch into the webview context (mobile equivalent of entering an iframe).
+      Polls for the context and throws when it never appears — see __enterWebContext (#705). --}}
+await __enterWebContext('{{escapeQuotes frameRef}}');

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/hover-action.hbs

@@ -1,2 +1,6 @@
-{{!-- No hover on touch devices — no-op. (Hover-revealed content is normally already visible on mobile;
-      if a tap is actually required, use `User tap [X]` instead.) --}}
+{{!-- No hover on a touch screen. This template used to hold only this comment, so the step compiled
+      to an empty line: the scenario claimed to exercise a hover, exercised nothing, and passed.
+      `hover-element` now declares platforms: ['web'], so a mobile project is refused at SG-W020
+      before reaching here — this throw is the second source agreeing with the first, the treatment
+      alert-fill-action already has. --}}
+throw new Error("[sungen] hover is not available on the appium adapter — a touch screen has no hover state. Content a hover reveals is normally already visible on mobile; if the interaction is genuinely required, use `User tap [X]`, otherwise tag the scenario @manual:M10.");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/hover-element-with-text.hbs

@@ -1,3 +1,4 @@
-{{!-- No hover on touch devices — no-op, mirrors hover-action.hbs. (A text-filtered hover target
-      is normally already visible on mobile; if a tap on the matching element is actually
-      required, use `User tap [X] item with {{value}}` instead.) --}}
+{{!-- No hover on a touch screen; mirrors hover-action.hbs. Text-filtering the target changes which
+      element is picked, not whether hovering it means anything. Braces are avoided in the message
+      below on purpose: handlebars would interpolate a literal mustache away to an empty string. --}}
+throw new Error("[sungen] hover is not available on the appium adapter — a touch screen has no hover state. To act on the item matching a value, tap it instead (`User tap [X] item with` your data ref); if the hover itself is the thing under test, tag the scenario @manual:M10.");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/table-paginate-action.hbs

@@ -0,0 +1,3 @@
+{{!-- An HTML paginator is a web control: a native list pages by scrolling, not by a next/prev
+      button pair, so there is nothing honest to emit here. --}}
+throw new Error("[sungen] 'go to next/prev page in table' drives an HTML paginator and is not supported on the appium adapter. Scroll the list instead, tap the pager control as a plain tap step, or tag this scenario @manual.");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/unknown-element-action.hbs

@@ -1,2 +1,11 @@
+{{#if (eq action "hover")}}
+{{!-- This template is reached by a MIXED pattern that serves click, double-click AND hover, so it
+      cannot be declared web-only without deleting tap from mobile. It also ignored `action` and
+      always clicked — which turned `hover [Target X] with {{ref}}` into a TAP on mobile. That is
+      worse than the silent no-op the pure hover patterns had: a tap has side effects a hover never
+      had, so the scenario changed app state while claiming to hover. Refuse instead. --}}
+throw new Error("[sungen] hover is not available on the appium adapter — a touch screen has no hover state, and this step would otherwise have tapped the element instead. Use `User tap` if acting on it is what you meant, or tag the scenario @manual:M10.");
+{{else}}
 {{!-- Fallback for an unrecognized action: tap an element by text / content-desc. --}}
 await $('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]').click();
+{{/if}}

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/have-value-assertion.hbs

@@ -1 +1,34 @@
-await expect({{> locator}}).toHaveValue('{{escapeQuotes dataValue}}');
+{{!-- Input-value assertion (mobile). The web template asserts toHaveValue(), which
+      expect-webdriverio implements as toHaveElementProperty('value') → GET
+      element/:id/property/value. That is a DOM command: UiAutomator2 does not implement
+      getElementProperty and answers 404 for every call, so the assertion used to fail
+      whatever the field held. Read the native value instead, exactly as
+      actions/capture-variable.hbs does for `capture: 'inputValue'`:
+        · iOS  — @value first, then @label (this is the input's OWN value, not its label)
+        · Android — getText() (GET element/:id/text), then @content-desc
+      `probeNative` is deliberately ignored: it drives a DOM tagName probe for ambiguous
+      dropdown/select/combobox targets on web, and a native tree has no tagName to probe. --}}
+{
+  const __el = await {{> locator}};
+  await __el.waitForDisplayed();
+  const __expected = String('{{escapeQuotes dataValue}}').trim();
+  const __sources = driver.isIOS
+    ? [await __el.getAttribute('value'), await __el.getAttribute('label')]
+    : [await __el.getText(), await __el.getAttribute('content-desc')];
+  let __actual = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
+  {{!-- iOS only, and only when we EXPECT empty: some WebDriverAgent versions echo an empty
+        UITextField's placeholder back as its @value. The XCUITest driver documents @value as
+        "a complex attribute whose calculation algorithm depends on the actual element type"
+        and promises nothing for an empty field, so the behaviour varies by WDA version.
+        @placeholderValue is a supported XCUITest attribute; an exact match means the field is
+        empty and we simply read its placeholder. Gated on __expected === '' so a non-empty
+        assertion pays no extra round-trip and its behaviour is bit-for-bit unchanged. --}}
+  if (driver.isIOS && __expected === '' && __actual !== '') {
+    let __placeholder = null;
+    try { __placeholder = await __el.getAttribute('placeholderValue'); } catch { /* attribute unsupported on this node */ }
+    if (__placeholder && String(__placeholder).trim() === __actual) __actual = '';
+  }
+  if (__actual !== __expected) {
+    throw new Error(`[sungen] Expected value "${__expected}" but element reads "${__actual}"`);
+  }
+}

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/label-value-assertion.hbs

@@ -1,12 +1,20 @@
-{{!-- Label-value assertion (mobile): locate a visible text node carrying the value.
-      Android renders text into @text; iOS (RN/Flutter) into @label/@value. The web variant
-      matches "label: value" as one string — native trees keep label and value as separate
-      nodes, so only the value is matched here. The expected value must stay a standalone
-      quoted literal so the runtime-data transform can swap it for testData.get(...). --}}
+{{!-- Label-value assertion (mobile), NO selectors.yaml entry: locate a visible node carrying
+      the value anywhere on screen. The web variant matches "label: value" as one string —
+      native trees keep label and value as separate nodes, so only the value is matched here.
+      Declare an entry for the ref to assert a specific element instead (#666).
+
+      Android publishes text into @text (native/RN) or @content-desc (Flutter Semantics), and
+      which one is populated is a property of the toolkit, not of the widget. This used to be
+      `UiSelector().text(...)`, which cannot read @content-desc at all and so missed on every
+      Flutter screen; UiSelector has no OR, hence the xpath. iOS scatters it across
+      label/value, which the predicate already ORs.
+
+      The expected value must stay a standalone quoted literal so the runtime-data transform
+      can swap it for testData.get(...). --}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
   const __sel = driver.isIOS
     ? `-ios predicate string:label == "${__expected}" OR value == "${__expected}"`
-    : `android=new UiSelector().text("${__expected}")`;
+    : `//*[@text="${__expected}" or @content-desc="${__expected}"]`;
   await expect($(__sel)).toBeDisplayed();
 }

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

@@ -8,7 +8,7 @@
 await expect({{> locator}}).toBeDisplayed();
 {{~else if scope~}}
 await expect({{> locator}}).toBeDisplayed();
-{{~else if nth~}}
+{{~else if (gte nth -1)~}}
 await expect({{> locator}}).toBeDisplayed();
 {{~else~}}
 await __assertVisible({{> appium-selector-expr}});

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/go-back-action.hbs

@@ -0,0 +1,21 @@
+{{!-- The OS/hardware back gesture. NOT the in-app Back button, and the difference is the whole
+      point: Android's system back does NOT run the screen's own handler unless the app wires it
+      (onBackPressed / BackHandler), so a defect on this path is invisible to a `tap [Back]`
+      scenario. That is exactly why `viewpoint-ledger.ts` treats the in-app control as a wrong
+      substitution for the "OS/hardware back gesture" theme (#626) — and why this template has to
+      exist for that theme to have any answer other than @manual.
+
+      Android: KEYCODE_BACK through the execute alias rather than `driver.pressKeyCode(4)`, for the
+      same reason `location-services-action` uses `mobile: isGpsEnabled` — WDIO v9 dropped the
+      legacy JSONWP wrappers, while a driver extension call cannot be removed from under us.
+
+      iOS: there IS no hardware back. `driver.back()` is WebDriverAgent's NAVIGATION back (it drives
+      the nav-bar back affordance), not the user's edge swipe-back gesture. Both OSes are therefore
+      implemented — the matrix reads ✅/✅ and the semantic difference is stated here and in the
+      matrix note, rather than dressed up as a refusal it is not. --}}
+if (driver.isIOS) {
+  // WDA navigation-back — NOT the user's swipe-back gesture; iOS exposes no hardware back key.
+  await driver.back();
+} else {
+  await driver.execute('mobile: pressKey', { keycode: 4 }); // KEYCODE_BACK — the real hardware back
+}

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/long-press-action.hbs

@@ -1,4 +1,8 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — `driver.execute` skips WDIO's implicit existence wait, so an
+  // undefined elementId surfaces as an opaque coordinates/offset error instead of the not-found
+  // that actually happened (#668).
+  if (!e.elementId) throw new Error((e as any).error?.message || `Element not found: ${e.selector}`);
   // XCUITest `mobile: touchAndHold` takes SECONDS; UiAutomator2 `mobile: longClickGesture` takes ms.
   if (driver.isIOS) { await driver.execute('mobile: touchAndHold', { elementId: e.elementId, duration: {{durationMs}} / 1000 }); }
   else { await driver.execute('mobile: longClickGesture', { elementId: e.elementId, duration: {{durationMs}} }); }

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/pinch-zoom-action.hbs

@@ -1,4 +1,8 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — `driver.execute` skips WDIO's implicit existence wait, so an
+  // undefined elementId surfaces as an opaque coordinates/offset error instead of the not-found
+  // that actually happened (#668).
+  if (!e.elementId) throw new Error((e as any).error?.message || `Element not found: ${e.selector}`);
   // XCUITest `mobile: pinch`: scale >1 zooms in, <1 zooms out (velocity sign must match).
   if (driver.isIOS) { await driver.execute('mobile: pinch', { elementId: e.elementId, scale: {{#if zoomOut}}0.5{{else}}2{{/if}}, velocity: {{#if zoomOut}}-1{{else}}1{{/if}} }); }
   else { await driver.execute('mobile: {{#if zoomOut}}pinchCloseGesture{{else}}pinchOpenGesture{{/if}}', { elementId: e.elementId, percent: 0.75 }); }

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/set-geolocation-action.hbs

@@ -1,2 +1,18 @@
+{{#if missing}}
+{{!-- No coordinates in the step and no data reference to read. Refuse by name: this used to default
+      to latitude 0 / longitude 0, which is Null Island — a real place, so the test passed there. --}}
+throw new Error("[sungen] cannot set location: no coordinates and no data reference in \"{{escapeQuotes missing}}\". Write the numbers inline (`User set location to 10.7769, 106.7009`), or point at a test-data key holding \"<latitude> <longitude>\".");
+{{else}}
+{{#if dataRef}}
+{{!-- Coordinates read from test-data AT RUN TIME, so one compiled spec serves every environment. --}}
+await (async () => {
+  const __raw = String(testData.get('{{dataRef}}'));
+  const __nums = __raw.match(/-?\d+(?:\.\d+)?/g) || [];
+  if (__nums.length < 2) throw new Error(`[sungen] test-data '{{dataRef}}' = "${__raw}" — setting a location needs two numbers, "<latitude> <longitude>"; found ${__nums.length}.`);
+  await driver.setGeoLocation({ latitude: Number(__nums[0]), longitude: Number(__nums[1]), altitude: 0 });
+})();
+{{else}}
 {{!-- Mock the device GPS location. --}}
 await driver.setGeoLocation({ latitude: {{latitude}}, longitude: {{longitude}}, altitude: 0 });
+{{/if}}
+{{/if}}

package/dist/generators/test-generator/adapters/appium/templates/steps/partials/locator.hbs

@@ -9,7 +9,15 @@
       scroll-into-view, so a below-fold / nav-occluded element is scrolled into the safe band before any
       find/tap/assert (Appium has no auto-scroll). Parent/scope/nth chains keep the plain `$()` — those
       resolve within a container / by index where a blind scroll doesn't apply.
+      `nth` is an INDEX, gated numerically (`gte nth -1`), not on truthiness (#720): `{{#if nth}}` read
+      `nth: 0` — the index every doc page uses as its example — as "no index declared" and sent it down
+      the __ensureVisible branch, while the web adapter indexed it, so the two adapters disagreed on the
+      one value authors actually write. It renders `(await $$(expr)).at(n)`: `$$` is a
+      ChainablePromiseArray in WDIO v9, so the old `$$(expr)[n]` indexed a promise and was `undefined`
+      for EVERY n (the awaited form is what the mobile helpers elsewhere in the emitted spec already
+      use), and `.at()` carries `-1` = last match with no second branch. The resolver has already
+      normalised anything outside `>= -1` to undefined and reported it as SG-W018.
       `plain=true` (passed by is-hidden-assertion) also forces the bare `$()`: an element asserted HIDDEN
       is expected to be absent, so scroll-hunting for it is both pointless and harmful — the 12x down-scroll
       would drag the screen to the bottom and strand later same-scenario steps that sit above. --}}
-{{~#if parentLocator~}}{{parentLocator}}.{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{~else~}}{{#if scope}}$('~{{escapeQuotes scope}}').{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{else}}{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}{{#if plain}}$({{> appium-selector-expr}}){{else}}(await __ensureVisible({{> appium-selector-expr}})){{/if}}{{/if}}{{/if}}{{~/if~}}
+{{~#if parentLocator~}}{{#if (gte nth -1)}}(await {{parentLocator}}.$$({{> appium-selector-expr}})).at({{nth}}){{else}}{{parentLocator}}.$({{> appium-selector-expr}}){{/if}}{{~else~}}{{#if scope}}{{#if (gte nth -1)}}(await $('~{{escapeQuotes scope}}').$$({{> appium-selector-expr}})).at({{nth}}){{else}}$('~{{escapeQuotes scope}}').$({{> appium-selector-expr}}){{/if}}{{else}}{{#if (gte nth -1)}}(await $$({{> appium-selector-expr}})).at({{nth}}){{else}}{{#if plain}}$({{> appium-selector-expr}}){{else}}(await __ensureVisible({{> appium-selector-expr}})){{/if}}{{/if}}{{/if}}{{~/if~}}

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

@@ -1,6 +1,14 @@
 {{#if platform}}
 // sungen:platform={{platform}}
 {{/if}}
+{{#if screenshotOnFailure}}
+// @screenshot:on-failure — used to be web-only and silently dropped on mobile.
+// wdio.conf.ts's afterTest hook already captures screenshot + page source + device log for EVERY
+// mobile failure, so the tag is not what turns evidence on. What it declares is that this feature's
+// evidence is ESSENTIAL: it survives SUNGEN_MOBILE_EVIDENCE=off, which otherwise suppresses capture
+// for the run. Set at module load, so it covers every scenario in this spec.
+(globalThis as Record<string, unknown>).__sungenForceEvidence = true;
+{{/if}}
 {{#if runtimeData}}
 
 const testData = TestDataLoader.load('{{screenName}}', '{{featureFileName}}');
@@ -202,6 +210,36 @@ async function __assertCheckedState(el: WebdriverIO.Element, expected: boolean,
   }
   throw new Error(`Expect ${label} to be ${want} — read [${signals.map(s => `${s.source} → ${s.value}`).join(', ')}]`);
 }
+
+// Entering a "frame" on a native driver means switching into the WebView CONTEXT — there is no
+// iframe to locate. That context does not exist until the WebView runtime has created it, and the
+// tap that kicks off the navigation returns long before that, so a ONE-SHOT getContexts() reads a
+// list that holds only NATIVE_APP. Skipping the switch on that reading is the worst possible
+// answer: every later step then searches the native tree, where a hybrid WebView is a SINGLE
+// opaque leaf with no children — the target can never appear there, so no downstream wait can
+// recover it and the run dies with a misleading "element still not displayed" (#705). Poll for the
+// context instead, and throw when it never arrives: a step that reads "switch to X frame" must
+// never quietly not switch.
+async function __enterWebContext(label: string): Promise<void> {
+  const budget = Number((driver as any)?.options?.waitforTimeout) || 30000;
+  const deadline = Date.now() + budget;
+  let seen: any[] = [];
+  for (;;) {
+    seen = await driver.getContexts();
+    const web = seen.find(c => /WEBVIEW|CHROMIUM/i.test(typeof c === 'string' ? c : c.id));
+    if (web) { await driver.switchContext(typeof web === 'string' ? web : web.id); return; }
+    if (Date.now() >= deadline) break;
+    await driver.pause(500);
+  }
+  throw new Error(
+    `[sungen] "switch to ${label} frame" — no WEBVIEW/CHROMIUM context appeared within ${budget}ms ` +
+    `(contexts seen: ${JSON.stringify(seen)}). The driver is still in NATIVE_APP, where a hybrid WebView ` +
+    `is one opaque node with no children, so every later step would fail as "element not displayed" ` +
+    `while the real cause is this switch. If the transition is genuinely slower than ${budget}ms, raise ` +
+    `waitforTimeout in wdio.conf.ts; if the screen has no WebView, drop the frame step and assert the ` +
+    `native markers instead.`,
+  );
+}
 {{#if singleAuthRole}}
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -332,23 +370,25 @@ describe('{{featureName}}', () => {
   // @auth:{{singleAuthRole}} — authenticate ONCE before any scenario; the session persists across
   // the per-scenario relaunch below (noReset:true). Throws (blocks the spec) if login can't be done.
   before(async () => {
-{{#if appPackage}}
     // Relaunch to a known launch screen first — the session may attach to the app in any state.
     // Platform-aware id (NOT the Android literal): on iOS a @platform:mobile feature's app is the
     // dual-id bundle id — a literal appPackage here would throw and block the whole spec.
-    // (__resolveAppId is a hoisted function declaration in this describe scope.)
+    // (__resolveAppId is a hoisted function declaration in this describe scope. It is no longer
+    // gated on a `Path:`-derived package (#669): it resolves the session capability too, and throws
+    // a named error when nothing supplies an id at all.)
     const __AUTH_APP__ = __resolveAppId();
     try { await driver.terminateApp(__AUTH_APP__); } catch { /* not running */ }
     await driver.activateApp(__AUTH_APP__);
-{{/if}}
     await __ensureAuth('{{singleAuthRole}}');
   });
 
 {{/if}}
-{{#if appPackage}}
   // Multi-app: this feature's app (from the `Path:` line). Reset to its launch screen before each
   // scenario so one `wdio run` can host screens from different apps — each spec launches its own.
   // The `Path:` holds the ANDROID package (or, for an @platform:ios feature, the iOS bundle id).
+  // EMPTY when the feature declared no usable `Path:` (#669) — the session capability then supplies
+  // the id (see __resolveAppId). Emitted unconditionally so that a feature without a `Path:` still
+  // gets per-scenario reset + Background instead of silently dropping to a once-per-file before().
   const __APP_PKG_DEFAULT__ = '{{appPackage}}';
 {{#if iosBundleId}}
   // Per-feature iOS bundle id from the dual-id `Path: <androidPkg>/<activity> | <iosBundleId>` —
@@ -358,13 +398,26 @@ describe('{{featureName}}', () => {
 {{/if}}
   // Platform-aware app id: an @platform:mobile spec runs on BOTH OSes. On iOS prefer the feature's own
   // bundle id (dual-id Path), then the session cap (IOS_BUNDLE_ID in wdio.conf), then the Path value;
-  // on Android (or any non-iOS session) use the Path package unchanged.
+  // on Android (or any non-iOS session) prefer the Path package, then the session cap.
+  // The session-capability fallback (#669) is what lets a feature with no app-package `Path:` keep a
+  // real per-scenario reset: wdio.conf sets `appium:appPackage` for the run, so the id the compiler
+  // could not read off the feature file is almost always present here. Throwing when NOTHING supplies
+  // it is deliberate — the alternative was the silent once-per-file before() this issue is about,
+  // where scenarios leak tab/scroll/login state into each other and the suite lies about why it
+  // failed. SG-W029 already named this at compile time, so this throw is never the first warning.
   function __resolveAppId(): string {
-    if (typeof driver !== 'undefined' && driver.isIOS) {
-      const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
-      return {{#if iosBundleId}}__IOS_BUNDLE__ || {{/if}}caps['appium:bundleId'] || caps['bundleId'] || __APP_PKG_DEFAULT__;
+    const caps = (typeof driver !== 'undefined' ? (driver.requestedCapabilities || {}) : {}) as Record<string, string>;
+    const resolved = (typeof driver !== 'undefined' && driver.isIOS)
+      ? ({{#if iosBundleId}}__IOS_BUNDLE__ || {{/if}}caps['appium:bundleId'] || caps['bundleId'] || __APP_PKG_DEFAULT__ || caps['appium:appPackage'] || caps['appPackage'])
+      : (__APP_PKG_DEFAULT__ || caps['appium:appPackage'] || caps['appPackage'] || caps['appium:bundleId'] || caps['bundleId']);
+    if (!resolved) {
+      throw new Error(
+        `[sungen] cannot resolve this app's id, so no per-scenario reset is possible (SG-W029). ` +
+        `Add an app-package \`Path:\` to the feature — \`Path: com.example.app/.MainActivity\` — ` +
+        `or set APP_PACKAGE (Android) / IOS_BUNDLE_ID (iOS) so wdio.conf puts it on the session.`,
+      );
     }
-    return __APP_PKG_DEFAULT__;
+    return resolved;
   }
   // ── Reset tier ────────────────────────────────────────────────────────────────────────────────
   // How much state each scenario starts from (`@reset:` on the Feature; default `soft`):
@@ -575,20 +628,6 @@ describe('{{featureName}}', () => {
 {{/if}}
   });
 
-{{/if}}
-{{#unless appPackage}}
-{{#if backgroundSteps}}
-  before(async () => {
-{{#each backgroundSteps}}
-{{#if comment}}
-    // {{comment}}
-{{/if}}
-{{code}}
-{{/each}}
-  });
-
-{{/if}}
-{{/unless}}
 {{#if beforeAll}}
 {{beforeAll}}
 

package/dist/generators/test-generator/adapters/index.d.ts

@@ -1,4 +1,4 @@
-export { TestGeneratorAdapter, TestFileData, ScenarioData, StepTemplateData, LocatorExpression } from './adapter-interface';
+export { TestGeneratorAdapter, TestFileData, ScenarioData, StepTemplateData, LocatorExpression, HookStep, HookRenderData } from './adapter-interface';
 export { AdapterRegistry, adapterRegistry, DriverNotInstalledError } from './adapter-registry';
 export { PlaywrightAdapter } from './playwright/playwright-adapter';
 export { AppiumAdapter } from './appium/appium-adapter';

package/dist/generators/test-generator/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/generators/test-generator/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC5H,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/generators/test-generator/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACtJ,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/generators/test-generator/adapters/playwright/playwright-adapter.d.ts

@@ -1,4 +1,4 @@
-import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions } from '../adapter-interface';
+import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions, HookRenderData } from '../adapter-interface';
 /**
  * PlaywrightAdapter
  * Generates Playwright TypeScript test code using Handlebars templates
@@ -18,24 +18,9 @@ export declare class PlaywrightAdapter implements TestGeneratorAdapter {
             code: string;
         }>;
     }): string;
-    renderBeforeAll(data: {
-        steps: Array<{
-            comment?: string;
-            code: string;
-        }>;
-    }): string;
-    renderAfterEach(data: {
-        steps: Array<{
-            comment?: string;
-            code: string;
-        }>;
-    }): string;
-    renderAfterAll(data: {
-        steps: Array<{
-            comment?: string;
-            code: string;
-        }>;
-    }): string;
+    renderBeforeAll(data: HookRenderData): string;
+    renderAfterEach(data: HookRenderData): string;
+    renderAfterAll(data: HookRenderData): string;
     renderStep(templateName: string, data: any): string;
 }
 //# sourceMappingURL=playwright-adapter.d.ts.map

package/dist/generators/test-generator/adapters/playwright/playwright-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-adapter.d.ts","sourceRoot":"","sources":["../../../../../src/generators/test-generator/adapters/playwright/playwright-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG9G;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,QAAQ,CAAC,aAAa,gBAAgB;IACtC,QAAQ,CAAC,aAAa,cAAc;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,cAAc,CAAiB;;IAQvC,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAI1C,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAI1C,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM;IAIrD,gBAAgB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,MAAM;IAIpF,eAAe,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,MAAM;IAInF,eAAe,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,MAAM;IAInF,cAAc,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,MAAM;IAIlF,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,MAAM;CAGpD"}
+{"version":3,"file":"playwright-adapter.d.ts","sourceRoot":"","sources":["../../../../../src/generators/test-generator/adapters/playwright/playwright-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG9H;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,QAAQ,CAAC,aAAa,gBAAgB;IACtC,QAAQ,CAAC,aAAa,cAAc;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,cAAc,CAAiB;;IAQvC,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAI1C,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAI1C,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM;IAIrD,gBAAgB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,MAAM;IAIpF,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAI7C,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAI7C,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAI5C,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,MAAM;CAGpD"}

package/dist/generators/test-generator/adapters/playwright/playwright-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-adapter.js","sourceRoot":"","sources":["../../../../../src/generators/test-generator/adapters/playwright/playwright-adapter.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB,2DAAuD;AAEvD;;;GAGG;AACH,MAAa,iBAAiB;IAM5B;QALS,kBAAa,GAAG,YAAY,CAAC;QAC7B,kBAAa,GAAG,UAAU,CAAC;QAKlC,2CAA2C;QAC3C,IAAI,CAAC,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACtD,IAAI,CAAC,cAAc,GAAG,IAAI,gCAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9D,CAAC;IAED,cAAc,CAAC,IAAkB;QAC/B,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,cAAc,CAAC,IAAkB;QAC/B,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,aAAa,CAAC,OAA8B;QAC1C,OAAO,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,gBAAgB,CAAC,IAA0D;QACzE,OAAO,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAED,eAAe,CAAC,IAA0D;QACxE,OAAO,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,eAAe,CAAC,IAA0D;QACxE,OAAO,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,cAAc,CAAC,IAA0D;QACvE,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,UAAU,CAAC,YAAoB,EAAE,IAAS;QACxC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;CACF;AA3CD,8CA2CC"}
+{"version":3,"file":"playwright-adapter.js","sourceRoot":"","sources":["../../../../../src/generators/test-generator/adapters/playwright/playwright-adapter.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB,2DAAuD;AAEvD;;;GAGG;AACH,MAAa,iBAAiB;IAM5B;QALS,kBAAa,GAAG,YAAY,CAAC;QAC7B,kBAAa,GAAG,UAAU,CAAC;QAKlC,2CAA2C;QAC3C,IAAI,CAAC,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACtD,IAAI,CAAC,cAAc,GAAG,IAAI,gCAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9D,CAAC;IAED,cAAc,CAAC,IAAkB;QAC/B,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,cAAc,CAAC,IAAkB;QAC/B,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,aAAa,CAAC,OAA8B;QAC1C,OAAO,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,gBAAgB,CAAC,IAA0D;QACzE,OAAO,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAED,eAAe,CAAC,IAAoB;QAClC,OAAO,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,eAAe,CAAC,IAAoB;QAClC,OAAO,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,cAAc,CAAC,IAAoB;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,UAAU,CAAC,YAAoB,EAAE,IAAS;QACxC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;CACF;AA3CD,8CA2CC"}

package/dist/generators/test-generator/adapters/playwright/templates/after-all.hbs

@@ -1,8 +1,26 @@
-  test.afterAll(async ({ request }) => {
+  test.afterAll(async () => {
+{{#if collect}}
+    // Hook checks are collected: every failed step is recorded and the hook fails ONCE with the full list
+    const __hookFailures: string[] = [];
+{{/if}}
 {{#each steps}}
 {{#if comment}}
     // {{comment}}
 {{/if}}
+{{#if wrap}}
+    try {
+{{code}}
+    } catch (e) {
+      __hookFailures.push({{label}} + ': ' + String((e as Error).message).split('\n')[0]);
+{{#if stopOnFailure}}
+      expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
+    }
+{{else}}
 {{code}}
+{{/if}}
 {{/each}}
+{{#if collect}}
+    expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
   });

package/dist/generators/test-generator/adapters/playwright/templates/after-each.hbs

@@ -1,8 +1,26 @@
   test.afterEach(async ({ page }) => {
+{{#if collect}}
+    // Hook checks are collected: every failed step is recorded and the hook fails ONCE with the full list
+    const __hookFailures: string[] = [];
+{{/if}}
 {{#each steps}}
 {{#if comment}}
     // {{comment}}
 {{/if}}
+{{#if wrap}}
+    try {
+{{code}}
+    } catch (e) {
+      __hookFailures.push({{label}} + ': ' + String((e as Error).message).split('\n')[0]);
+{{#if stopOnFailure}}
+      expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
+    }
+{{else}}
 {{code}}
+{{/if}}
 {{/each}}
+{{#if collect}}
+    expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
   });

package/dist/generators/test-generator/adapters/playwright/templates/before-all.hbs

@@ -1,8 +1,26 @@
-  test.beforeAll(async ({ request }) => {
+  test.beforeAll(async () => {
+{{#if collect}}
+    // Hook checks are collected: every failed step is recorded and the hook fails ONCE with the full list
+    const __hookFailures: string[] = [];
+{{/if}}
 {{#each steps}}
 {{#if comment}}
     // {{comment}}
 {{/if}}
+{{#if wrap}}
+    try {
+{{code}}
+    } catch (e) {
+      __hookFailures.push({{label}} + ': ' + String((e as Error).message).split('\n')[0]);
+{{#if stopOnFailure}}
+      expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
+    }
+{{else}}
 {{code}}
+{{/if}}
 {{/each}}
+{{#if collect}}
+    expect(__hookFailures, 'Hook preconditions not met').toEqual([]);
+{{/if}}
   });

package/dist/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -18,6 +18,9 @@ import { {{urlAssertImports}} } from '{{basePath}}/url-assert';
 {{#if regexEscapeImport}}
 import { escapeRegExp } from '{{basePath}}/regex-escape';
 {{/if}}
+{{#if checkedStateImports}}
+import { {{checkedStateImports}} } from '{{basePath}}/checked-state';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/dist/generators/test-generator/adapters/playwright/templates/steps/actions/check-action.hbs

@@ -1 +1,6 @@
-await {{> locator}}.check();
+{{!-- Playwright's .check() accepts ONLY native checkbox/radio and role=checkbox|radio|switch —
+      a `<button aria-pressed>` toggle threw "Not a checkbox or radio button" (#675). The branch
+      cannot be decided here: a testid/CSS selector carries no role, so the element is inspected at
+      run time by setCheckedState (specs/checked-state.ts), which also keeps the step IDEMPOTENT —
+      the reason `check` exists rather than `click`. --}}
+await setCheckedState({{> locator}}, true, '{{escapeQuotes selectorRef}}'{{> checked-opts cls=checkedClass attr=checkedAttribute}});