@sun-asterisk/sungen 3.2.18 → 3.2.20

package/src/orchestrator/templates/specs-url-assert.ts

@@ -0,0 +1,134 @@
+/* eslint-disable */
+/**
+ * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
+ *
+ * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ *
+ * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
+ * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
+ * generated suite in the field: regenerate everything, re-review every newly-red test. Behind a
+ * helper the same correction ships as a runtime patch. The generator's job shrinks to what it
+ * alone knows — the pathname pattern — and the semantics live in one readable place.
+ *
+ * Why a predicate and not two assertions. The shape before this one was
+ *   await expect(page).toHaveURL(/\/vi\/search/);      // unanchored: passes on /vi/search-x
+ *   expect(page.url()).toContain('<query>');           // synchronous, one-shot: never retries
+ * — two half-checks, neither anchored, and nothing ever compared pathname and query together.
+ * `toHaveURL(predicate)` is web-first (it retries like any other assertion), receives a parsed
+ * URL, and needs no regex escaping of runtime values, which is what forced the split.
+ */
+
+export interface UrlExpectation {
+  /**
+   * Anchored pathname pattern, compiled by the generator from the page selector's `value`
+   * (`:id` segments already wildcarded). Anchored against `u.pathname` ONLY: pathname never
+   * carries the query, so `^…$` is exact there — the same source that was unsafe to anchor
+   * against a full URL.
+   */
+  pathname: RegExp;
+  /**
+   * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
+   * `undefined` means the step declared nothing, which is itself an assertion — see below.
+   */
+  declared?: string;
+  /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
+  dataRef?: string;
+}
+
+/**
+ * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
+ * (`Given User is on [X] page with {{v}}`).
+ *
+ * Why this is not a plain `base + path + value`. It used to be, and an author writing the value as a
+ * whole relative URL — the habit the assertion side already had to accommodate — navigated to
+ * `/vi/search/vi/search?q=1`: the page's own path, twice. The Then side then asserted the real path
+ * correctly, so the scenario could never go green.
+ *
+ * `base` (the configured baseURL, possibly '') and `path` (the page selector's value) arrive
+ * SEPARATELY so a value that carries its own rooted path replaces the page's path without also
+ * discarding a path prefix baked into the baseURL — a deployment under `https://host/tenant-a`
+ * would otherwise navigate to the wrong tenant, and only when a `with {{v}}` was present, which is
+ * exactly the kind of inconsistency nobody would think to look for.
+ *
+ * What it deliberately does NOT do is sanitize. A test may legitimately drive a MALFORMED query to
+ * prove the app rejects it (issue #464), so anything that is not a duplicated path is appended
+ * verbatim: no encoding, no normalising, no reordering.
+ */
+export function joinPath(base: string, path: string, declared?: string | null): string {
+  if (declared === undefined || declared === null || declared === '') return base + path;
+  const value = String(declared);
+  // A query/fragment appends — the overwhelmingly common shape, and the only one #464 needs.
+  if (value.startsWith('?') || value.startsWith('#')) return base + path + value;
+  // An absolute URL replaces everything: the author pasted a full address.
+  if (/^[a-z]+:\/\//i.test(value)) return value;
+  // A rooted path carries its own path, so it replaces the PAGE's path while everything the
+  // baseURL contributed — scheme, host, and any path prefix — is kept.
+  if (value.startsWith('/')) return base + value;
+  // Anything else is raw input the test wants appended as-is.
+  return base + path + value;
+}
+
+/**
+ * `u.pathname` is percent-encoded; a regex built from a selector's literal `value` is not, so a
+ * non-ASCII route (`/読取結果一覧`) could never match. Decoding can throw on a lone `%`, in which
+ * case the raw form is all there is.
+ */
+function decodedPath(pathname: string): string {
+  try {
+    return decodeURIComponent(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+/**
+ * Build the predicate for `expect(page).toHaveURL(...)`.
+ *
+ * Query semantics are deliberately asymmetric:
+ *   no `with {{v}}`  → the URL must carry NO query. A bare page means a bare page, so
+ *                      `/vi/search` does not pass on `/vi/search?x=1`.
+ *   `with {{v}}`     → every declared param must match; extra params are tolerated, so a
+ *                      tracking/UTM param the test never cared about cannot turn it red.
+ *                      A declared fragment is asserted too; a declared value carrying no query
+ *                      at all constrains the path only (the compiler warns: SG-W014).
+ */
+export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+  return (u: URL): boolean => {
+    if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname))) return false;
+
+    // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
+    // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
+    // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
+    // bare), the second is broken test-data. Only the generator knows which, and it says so by
+    // emitting `dataRef` exactly when the step carried a `with {{v}}`.
+    if (!dataRef) return u.search === '';
+
+    // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
+    // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these
+    // throws say "your test-data is wrong, and here is the key". An empty value used to parse to
+    // an empty param list, and `[].every()` is vacuously TRUE — it passed on any query at all.
+    if (declared === undefined || declared === null) {
+      throw new Error(`url assertion: test-data key "${dataRef}" is missing — nothing to assert`);
+    }
+    if (String(declared).trim() === '') {
+      throw new Error(`url assertion: test-data key "${dataRef}" is empty — nothing to assert`);
+    }
+
+    // Parsing against the live pathname as base lets ONE expression handle every shape an author
+    // writes: '?q=1' (query only), '/vi/search?q=1' (a whole relative URL — its path is ignored,
+    // the page selector already owns the path), and '#tab' (fragment only). The predecessor
+    // regex-stripped the prefix instead, which silently turned a value with NO query
+    // ('/vi/search') into a bogus param NAME — an assertion that could never be satisfied.
+    const d = new URL(String(declared), 'http://sungen.invalid' + u.pathname);
+
+    // getAll, not get: a multi-select filter (?tag=a&tag=b) is the exact case this assertion is
+    // for, and `get()` returns only the first value — so the correct URL failed. Comparing as a
+    // subset per key keeps this consistent with "extra params are tolerated", and makes param
+    // order meaningless, which is what a URL actually means.
+    const queryOk = [...d.searchParams].every(([k, v]) => u.searchParams.getAll(k).includes(v));
+
+    // Only assert a fragment the author actually declared.
+    const hashOk = !d.hash || d.hash === u.hash;
+    return queryOk && hashOk;
+  };
+}

package/src/orchestrator/test-data-guide.ts

@@ -129,6 +129,10 @@ const ENV_QA_EXAMPLE = `# Secret test data referenced as \${QA_*} in qa/**/test-
 # Per-environment overrides: .env.qa.<env> + run with SUNGEN_ENV=<env>.
 #
 # QA_ADMIN_PASSWORD=
+#
+# Web baseURL for this environment — overrides the static value in
+# playwright.config.ts (declare per env: .env.qa.dev, .env.qa.uat, ...).
+# SUNGEN_BASE_URL=
 `;
 
 /**