fix(e2e): make WelcomePortal recovery navigation locale-independent (#590)

* fix(e2e): make WelcomePortal recovery navigation locale-independent

Extracted from PR #583's already-converged fix for exactly this failure
class -- see #589 for the reproduced blocker and #532 for the broader
startup/navigation nondeterminism this belongs to.

ensureWelcomePortalEntry()'s Factory-Reset recovery fallback (used when a
pre-existing/leftover project causes a cold boot to land in the main
shell instead of the WelcomePortal) drove Settings/Data/Factory-Reset
navigation through English/German-only translated button-name regexes,
after trying to force English via localStorage + reload. The Playwright
accessibility snapshot from #589's failure proved that reload doesn't
reliably take effect before the English-only lookup runs, so the
recovery path fails deterministically whenever the rare landing-in-main-
chrome race triggers with any other persisted locale (Spanish, in the
observed case).

Replaces the whole recovery flow with stable, locale-independent
data-tour/data-testid anchors end to end:
- clickSettingsNavItem() (helpers.ts) -- mobile-aware Settings navigation
  keyed on data-tour="nav-settings"/"nav-more", not translated text.
- resolveStartupState() -- explicit WELCOME_PORTAL | MAIN_CHROME result
  instead of repeated isVisible().catch(() => false) boolean soup.
- settings-nav- testid on SettingsView's NavButton, and
  factory-reset-button / factory-reset-confirm-button testids on
  DataSection / SettingsModals, so the recovery flow never depends on
  translated labels.
- Sidebar.tsx gains the data-tour="nav-more" anchor the new helper
  needs -- traced as a required dependency not otherwise present on main.

Adds a dedicated regression test (onboarding-entry-precondition.spec.ts)
that deterministically reproduces the exact failure shape (persisted
main-chrome project + non-English language, Mobile Chrome and desktop)
instead of relying on the rare race to expose it.

Deliberately excludes #583's unrelated handleFactoryReset error-toast
refactor (hooks/useSettingsView.ts) and its tests -- orthogonal to this
locale-independence fix, left for #583's own convergence.

* docs: add QNBS-v3 annotations for the new E2E test-selector attributes

Sidebar.tsx's dataTour prop and DataSection.tsx's factory-reset-button
testid were extracted from #583 with a plain JSDoc / no comment; the
repo convention requires a single-line QNBS-v3 annotation on non-trivial
TS/TSX changes. No behavior change.

* test(e2e): assert applied locale, not just the persisted seed

The prior assertion only proved localStorage held 'es', which doesn't
prove the app actually rendered in Spanish -- a broken addInitScript
seed or a failed es bundle load could still pass this test vacuously in
English, the exact vacuity the original comment claimed to prevent.
document.documentElement.lang (set by I18nProvider/App.tsx on mount) is
the real applied-locale authority; assert that instead, using
Playwright's own auto-wait toHaveAttribute matcher rather than a bare
evaluate() + expect().

* chore(ci): exclude tests/ from codecov patch coverage

vitest.config.ts's own coverage.include list scopes measurement to
application source (App.tsx, index.tsx, register-sw.ts, app/, components/,
features/, hooks/, services/, packages/*/src/) -- tests/** was never
instrumented, by design, since it's test code, not application source.
No codecov.yml existed to tell Codecov the same thing, so any PR adding
substantial new logic to an E2E helper file (as #590 does in
tests/e2e/helpers.ts) got counted as uncovered diff lines it structurally
cannot have coverage data for, producing a false codecov/patch failure
regardless of how well the actual application-source changes in the same
diff were covered.

Mirrors vitest.config.ts's coverage.exclude entry for the same path.
Pure YAML config -- rationale here in the commit message, not an inline
comment, per repo convention.

* fix(ci): correct codecov.yml ignore key to top-level per documented schema

ignore: is a documented top-level codecov.yml key, not nested under
coverage: -- confirmed against docs.codecov.com and codecov.io/validate
(parses to the expected (?s:tests/.*)\Z regex). The previous shape was
accepted by YAML parsing but wasn't the schema Codecov's config loader
actually recognizes.

Author: qnbs

codecov.yml

@@ -0,0 +1,2 @@
+ignore:
+  - "tests/**"

components/SettingsView.tsx

@@ -38,14 +38,17 @@ import { ViewErrorBoundary } from './ui/ViewErrorBoundary';
 
 // --- SUB-COMPONENTS ---
 
+// QNBS-v3: stable data-testid lets E2E recovery navigation target a category without matching translated label text
 const NavButton: FC<{
+  id: string;
   icon: React.ReactNode;
   label: string;
   isActive: boolean;
   onClick: () => void;
-}> = React.memo(({ icon, label, isActive, onClick }) => (
+}> = React.memo(({ id, icon, label, isActive, onClick }) => (
   <button
     type="button"
+    data-testid={`settings-nav-${id}`}
     onClick={onClick}
     aria-current={isActive ? 'page' : undefined}
     className={`flex items-center flex-shrink-0 md:flex-shrink md:w-full px-3 py-2 text-left rounded-md transition-colors whitespace-nowrap md:whitespace-normal ${isActive ? 'bg-[var(--nav-background-active)] text-[var(--nav-text-active)]' : 'hover:bg-[var(--nav-background-hover)] text-[var(--sc-text-secondary)] hover:text-[var(--sc-text-primary)]'}`}
@@ -365,6 +368,7 @@ const SettingsViewUI: FC = () => {
               filteredNavCategories.map((cat) => (
                 <NavButton
                   key={cat.id}
+                  id={cat.id}
                   icon={cat.icon}
                   label={cat.label}
                   isActive={activeCategory === cat.id}
@@ -379,6 +383,7 @@ const SettingsViewUI: FC = () => {
                   .map((cat) => (
                     <NavButton
                       key={cat.id}
+                      id={cat.id}
                       icon={cat.icon}
                       label={cat.label}
                       isActive={activeCategory === cat.id}
@@ -396,6 +401,7 @@ const SettingsViewUI: FC = () => {
                       {groupCats.map((cat) => (
                         <NavButton
                           key={cat.id}
+                          id={cat.id}
                           icon={cat.icon}
                           label={cat.label}
                           isActive={activeCategory === cat.id}

components/Sidebar.tsx

@@ -77,7 +77,9 @@ const BottomTabItem: React.FC<{
   isActive: boolean;
   onClick: () => void;
   sectionId?: string;
-}> = React.memo(({ icon, label, isActive, onClick, sectionId }) => {
+  // QNBS-v3: stable data-tour anchor lets E2E recovery navigation find this button without matching translated label text
+  dataTour?: string;
+}> = React.memo(({ icon, label, isActive, onClick, sectionId, dataTour }) => {
   // QNBS-v3: colored icon dot for mobile tab bar via section SSOT
   const sectionConfig = sectionId ? APP_SECTIONS[sectionId as keyof typeof APP_SECTIONS] : null;
   const iconColor = sectionConfig && !isActive ? sectionConfig.textColor : '';
@@ -86,6 +88,7 @@ const BottomTabItem: React.FC<{
     <button
       type="button"
       onClick={onClick}
+      data-tour={dataTour}
       className={`relative flex flex-col items-center justify-center flex-1 min-h-[44px] py-2 transition-colors duration-200 touch-manipulation outline-none focus-visible:ring-2 focus-visible:ring-[var(--sc-ring-focus)] rounded-lg ${
         isActive ? 'text-[var(--nav-text-active)]' : 'text-[var(--sc-text-muted)]'
       }`}
@@ -201,6 +204,7 @@ export const Sidebar: React.FC<SidebarProps> = ({
           label={t('common.more')}
           isActive={isSidebarOpen || !isTabBarView}
           onClick={() => setIsSidebarOpen(!isSidebarOpen)}
+          dataTour="nav-more"
         />
       </nav>
 
@@ -299,4 +303,4 @@ export const Sidebar: React.FC<SidebarProps> = ({
       </aside>
     </>
   );
-};
+};

components/settings/DataSection.tsx

@@ -418,9 +418,11 @@ export const DataSection: FC = () => {
                   {t('settings.data.dangerZone.factoryReset.hint')}
                 </p>
               </div>
+              {/* QNBS-v3: stable data-testid lets E2E recovery navigation target this button without matching translated label text */}
               <Button
                 variant="danger"
                 size="sm"
+                data-testid="factory-reset-button"
                 onClick={() => setModal({ state: 'factoryReset', payload: {} })}
                 className="shrink-0"
               >

components/settings/SettingsModals.tsx

@@ -138,7 +138,12 @@ export const SettingsModals: FC = () => {
             <Button variant="secondary" onClick={() => setModal({ state: 'closed', payload: {} })}>
               {t('common.cancel')}
             </Button>
-            <Button variant="danger" onClick={() => void handleFactoryReset()}>
+            {/* QNBS-v3: stable data-testid lets E2E recovery navigation target this button without matching translated label text */}
+            <Button
+              variant="danger"
+              onClick={() => void handleFactoryReset()}
+              data-testid="factory-reset-confirm-button"
+            >
               {t('settings.data.dangerZone.factoryReset.modalConfirm')}
             </Button>
           </div>

tests/e2e/helpers.ts

@@ -29,6 +29,21 @@ export async function clickNavItem(page: Page, name: RegExp): Promise<void> {
   await page.locator('#sidebar-mobile').getByRole('button', { name }).click();
 }
 
+/** Locale-independent Settings navigation: same mobile-aware fallback as clickNavItem, keyed on the stable `data-tour="nav-settings"` anchor instead of translated visible text. */
+async function clickSettingsNavItem(page: Page): Promise<void> {
+  const desktopBtn = page.locator('#sidebar [data-tour="nav-settings"]');
+  if (await desktopBtn.isVisible({ timeout: 1500 }).catch(() => false)) {
+    await desktopBtn.click();
+    return;
+  }
+  // QNBS-v3: data-tour="nav-more" (not a translated /More/i label) so this stays locale-independent on a non-English mobile boot.
+  const moreBtn = page.locator('[data-tour="nav-more"]');
+  await expect(moreBtn).toBeVisible({ timeout: 8000 });
+  await moreBtn.click();
+  await page.locator('#sidebar-mobile').waitFor({ state: 'visible' });
+  await page.locator('#sidebar-mobile [data-tour="nav-settings"]').click();
+}
+
 // QNBS-v3: Stable Writer `#writer-section-select` + option handling avoids Playwright strict-mode / native-<option> visibility pitfalls that broke CI E2E.
 
 /** Writer section `<Select>` — stable id to avoid picking tone/tool comboboxes elsewhere on the page. */
@@ -147,6 +162,19 @@ export async function waitForMainChrome(page: Page): Promise<void> {
   ]);
 }
 
+/** QNBS-v3: explicit discriminated startup state, not boolean soup — repeatedly asking "is the portal visible?" via isVisible().catch(()=>false) can't distinguish "main chrome" from "still loading" and silently swallows genuine errors as false. */
+export type StartupState = 'WELCOME_PORTAL' | 'MAIN_CHROME';
+
+/** Resolves which of waitForSpaReady()'s two shapes the current document actually reached. */
+export async function resolveStartupState(page: Page): Promise<StartupState> {
+  await waitForSpaReady(page);
+  const portal = page.getByTestId('welcome-portal');
+  if (await portal.isVisible().catch(() => false)) {
+    return 'WELCOME_PORTAL';
+  }
+  return 'MAIN_CHROME';
+}
+
 /** Language toggle on the welcome portal (EN must be active for English copy in assertions). */
 export async function selectEnglish(page: Page): Promise<void> {
   const enBtn = page.getByRole('button', { name: /^EN$/i }).first();
@@ -179,36 +207,20 @@ export async function ensureBlankProject(page: Page): Promise<void> {
  * waitForSpaReady()'s two success shapes the app actually booted into. A cold CI boot has landed
  * in an already-mounted main shell with a persisted project instead of the portal — a startup-
  * state precondition gap distinct from the (fixed) portal-activation auto-seed race.
- * Contract: guarantees the portal is reached, locale-independently — it does NOT guarantee
- * English. A caller needing English selects it itself (export.spec.ts already does this for the
- * fresh-boot case). Recovers via the real Settings → Data & Backups → Factory Reset flow when
- * main chrome is active so no React/Redux/storage internals are touched — only supported app
- * behavior.
+ * Contract: guarantees the portal is reached, locale-independently. Recovers via the real
+ * Settings → Data & Backups → Factory Reset flow when main chrome is active so no React/Redux/
+ * storage internals are touched — only supported app behavior.
  */
 export async function ensureWelcomePortalEntry(page: Page): Promise<void> {
-  await waitForSpaReady(page);
   const portal = page.getByTestId('welcome-portal');
-  if (await portal.isVisible({ timeout: 3000 }).catch(() => false)) {
+  if ((await resolveStartupState(page)) === 'WELCOME_PORTAL') {
     return;
   }
-  // QNBS-v3: force English before the locale-dependent recovery flow below, or a persisted non-EN/DE language would hang it.
-  await page.evaluate(() => localStorage.setItem('worldscript-language', 'en'));
-  await page.reload();
-  await waitForSpaReady(page);
-  // QNBS-v3: this reload can itself race a pending debounced autosave and land back in WelcomePortal instead of main chrome — accept either state again rather than assuming main chrome.
-  if (await portal.isVisible({ timeout: 3000 }).catch(() => false)) {
-    return;
-  }
-  await waitForMainChrome(page);
-  await clickNavItem(page, /Settings/i);
-  await page
-    .getByRole('button', { name: /Data & Backups|Daten & Backups/i })
-    .first()
-    .click();
-  await page.getByRole('button', { name: /Factory Reset|Werkseinstellungen/i }).click();
-  await page
-    .getByRole('button', { name: /Delete everything & restart|Alles löschen & neu starten/i })
-    .click();
+  // QNBS-v3: every step below uses a stable data-tour/data-testid anchor, never translated text — Playwright's own docs say addInitScript execution order across registrations is unspecified, so this cannot rely on forcing a language first.
+  await clickSettingsNavItem(page);
+  await page.getByTestId('settings-nav-data').click();
+  await page.getByTestId('factory-reset-button').click();
+  await page.getByTestId('factory-reset-confirm-button').click();
   await waitForSpaReady(page);
   await expect(portal).toBeVisible({ timeout: 15000 });
 }

tests/e2e/onboarding-entry-precondition.spec.ts

@@ -42,6 +42,22 @@ test.describe('WelcomePortal entry precondition (CI-only)', () => {
     await expect(page.getByRole('button', { name: /Start a New Project/i })).toBeVisible();
   });
 
+  test('reaches the entry point via the recovery flow with a persisted non-English language, on Mobile Chrome and desktop alike', async ({
+    page,
+  }) => {
+    // QNBS-v3: a fresh boot lands on the portal regardless of locale — this combines a persisted main-chrome project with a non-English language so a mobile "More"-button locale regression actually fails, on every project including Mobile Chrome.
+    await page.goto('/');
+    await ensureBlankProject(page);
+    await expect(page.getByText(/All changes saved/i)).toBeVisible({ timeout: 10000 });
+    await page.addInitScript(() => localStorage.setItem('worldscript-language', 'es'));
+    await page.reload();
+    await waitForMainChrome(page);
+    // QNBS-v3: asserts the applied locale, not just the persisted seed — a broken addInitScript or a failed es bundle load could otherwise pass this test vacuously in English.
+    await expect(page.locator('html')).toHaveAttribute('lang', 'es');
+    await ensureWelcomePortalEntry(page);
+    await expect(page.getByTestId('welcome-portal')).toBeVisible();
+  });
+
   test('reaches the entry point when its own internal reload can race a pending autosave', async ({
     page,
   }) => {