@sdods/core 0.3.2 → 0.5.2

package/dist/config/runner.js

@@ -2,16 +2,51 @@ import { existsSync } from 'node:fs';
 import { join, resolve as resolvePath } from 'node:path';
 import { devices } from '@playwright/test';
 import { cucumberReporter, defineBddConfig } from 'playwright-bdd';
-import { runnerProjectName, runFiles } from '@sdods/contracts';
+import { EVIDENCE_DEFAULTS, RUNNER_SETUP_PHASE, runnerProjectName, runFiles, } from '@sdods/contracts';
 import { coreStepsPatterns } from '../steps/glob.js';
 import { combineTagExpr, normalizeTagExpr } from './tags.js';
 const DEVICE_FOR_BROWSER = {
     chromium: 'Desktop Chrome',
+    edge: 'Desktop Edge',
     firefox: 'Desktop Firefox',
     webkit: 'Desktop Safari',
     'mobile-chrome': 'Pixel 7',
     'mobile-safari': 'iPhone 15',
 };
+/**
+ * Browsers that are a branded channel of an engine rather than the bundled build.
+ *
+ * `devices['Desktop Edge']` only sets an Edge user-agent — its `defaultBrowserType` is still
+ * 'chromium' — so without an explicit channel Playwright launches the bundled Chromium and it
+ * merely claims to be Edge. The channel is what actually starts the browser the user installed.
+ */
+const CHANNEL_FOR_BROWSER = { edge: 'msedge' };
+/** The Playwright channel family a project-level `channel:` belongs to, for compatibility checks. */
+function channelFamily(channel) {
+    return channel.startsWith('msedge') ? 'msedge' : 'chrome';
+}
+/**
+ * The channel a run target launches with.
+ *
+ * A project-level `channel:` refines a branded browser, it does not redirect it: `channel: chrome`
+ * on a project that also runs `edge` must not make the `--edge` target launch Google Chrome, which
+ * would put a browser in the results under another browser's name.
+ */
+function channelFor(browser, projectChannel) {
+    const branded = CHANNEL_FOR_BROWSER[browser];
+    if (!branded) {
+        // Chromium-family engines take whatever the project asked for; other engines have no channels.
+        return browser === 'chromium' || browser === 'mobile-chrome' ? projectChannel : undefined;
+    }
+    if (projectChannel && channelFamily(projectChannel) === channelFamily(branded))
+        return projectChannel;
+    return branded;
+}
+/** The `use` keys that select the browser binary for a run target. */
+function browserUse(browser, projectChannel) {
+    const channel = channelFor(browser, projectChannel);
+    return { ...devices[DEVICE_FOR_BROWSER[browser]], ...(channel ? { channel } : {}) };
+}
 export const DASHBOARD_REPORTER = '@sdods/core/reporters/dashboard';
 /** Convenience for `sdods.runner.config.ts`: read the selection from SDODS_* env vars. */
 export function selectionFromEnv(env = process.env) {
@@ -32,6 +67,7 @@ export function selectionFromEnv(env = process.env) {
         allure: env.SDODS_ALLURE === '1',
         reporters: list(env.SDODS_REPORTERS),
         reporterMode: env.SDODS_REPORTER_MODE || 'default',
+        process: env.SDODS_PROCESS || undefined,
     };
 }
 /** Names (and identity) of the Playwright projects a selection would produce, without side effects. */
@@ -93,32 +129,40 @@ export function buildRunnerConfig(registry, sel = {}) {
         for (const k of Object.keys(envUse))
             if (envUse[k] === undefined)
                 delete envUse[k];
+        const byTag = p.retries?.byTag ?? {};
+        const pushProject = (project) => projects.push(...withRetriesByTag(project, byTag));
+        const { fullyParallel, setup } = runSettings(registry, entry.slug, p, sel.process);
+        // Playwright's own artifacts, per target so each project in a multi-project run keeps its own.
+        const evidenceUse = {
+            screenshot: p.evidence.screenshot,
+            video: p.evidence.video,
+            trace: p.evidence.trace,
+        };
         for (const layer of layers) {
             if (layer === 'recorded') {
                 const recordedDir = join(p.root, 'recorded');
                 if (!existsSync(recordedDir))
                     continue;
                 for (const browser of browsers) {
-                    projects.push({
+                    pushProject({
                         name: runnerProjectName({ project: p.slug, layer, browser }),
                         testDir: recordedDir,
                         testMatch: '**/*.spec.ts',
+                        fullyParallel,
                         snapshotPathTemplate: join(p.root, 'features', '__screenshots__', '{projectName}', '{platform}', '{arg}{ext}'),
                         use: {
-                            ...devices[DEVICE_FOR_BROWSER[browser]],
-                            ...(p.channel && (browser === 'chromium' || browser === 'mobile-chrome')
-                                ? { channel: p.channel }
-                                : {}),
+                            ...browserUse(browser, p.channel),
                             baseURL: cfg.env.ui.baseUrl,
                             testIdAttribute: p.testIdAttribute,
                             ...envUse,
+                            ...evidenceUse,
                             sdods: { project: p.slug, layer, browser },
                         },
                     });
                 }
                 continue;
             }
-            const testDir = defineBddConfig({
+            const generate = (tags, outDir) => defineBddConfig({
                 features: `${toPosix(p.root)}/features/**/*.feature`,
                 steps: [
                     ...coreStepsPatterns(cfg.project.steps?.core?.exclude ?? []),
@@ -127,42 +171,66 @@ export function buildRunnerConfig(registry, sel = {}) {
                 ],
                 // Each run generates into its own dir (cleaned by `sdods run`), lint/export into `.lint`,
                 // so concurrent runs and tooling never race on generated specs.
-                outputDir: `${toPosix(join(cfg.runtime.repoRoot, '.sdods/generated', sel.lint ? '.lint' : (sel.runId ?? 'adhoc'), p.slug, layer))}`,
+                outputDir: `${toPosix(join(cfg.runtime.repoRoot, '.sdods/generated', sel.lint ? '.lint' : (sel.runId ?? 'adhoc'), p.slug, outDir))}`,
                 featuresRoot: `${toPosix(p.root)}/features`,
                 // Explicit: scenarios that only use core steps cannot let bddgen guess the project test instance.
                 importTestFrom: `${toPosix(p.root)}/steps/fixtures.ts`,
                 disableWarnings: { importTestFrom: true },
-                tags: combineTagExpr(`@${layer}`, sel.tags),
+                tags,
                 examplesTitleFormat: 'Example #<_index_>',
                 missingSteps: sel.lint ? 'fail-on-gen' : 'fail-on-run',
                 aiFix: { promptAttachment: true },
                 quotes: 'single',
             });
+            const layerExpr = combineTagExpr(`@${layer}`, sel.tags);
+            // Setup scenarios are generated on their own: whatever --tags selects, the gate still runs,
+            // and a scenario that is setup never runs a second time inside the target it gates.
+            const testDir = generate(setup ? `(${layerExpr}) and not (${setup.tags})` : layerExpr, layer);
             bddConfigs++;
+            const setupTestDir = setup
+                ? generate(combineTagExpr(`@${layer}`, setup.tags), `${layer}--${RUNNER_SETUP_PHASE}`)
+                : undefined;
+            if (setupTestDir)
+                bddConfigs++;
+            /** Push a target, preceded by its setup companion when the project has a setup tier. */
+            const pushTarget = (parts, target) => {
+                const name = runnerProjectName({ project: p.slug, ...parts });
+                if (setupTestDir) {
+                    const setupName = runnerProjectName({
+                        project: p.slug,
+                        ...parts,
+                        phase: RUNNER_SETUP_PHASE,
+                    });
+                    projects.push({ ...target, name: setupName, testDir: setupTestDir });
+                    pushProject({ ...target, name, testDir, dependencies: [setupName] });
+                }
+                else {
+                    pushProject({ ...target, name, testDir });
+                }
+            };
             if (layer === 'api') {
-                projects.push({
-                    name: runnerProjectName({ project: p.slug, layer }),
-                    testDir,
-                    use: { sdods: { project: p.slug, layer } },
+                pushTarget({ layer }, {
+                    fullyParallel,
+                    use: {
+                        ...evidenceUse,
+                        sdods: { project: p.slug, layer },
+                    },
                 });
                 continue;
             }
             for (const browser of browsers) {
-                projects.push({
-                    name: runnerProjectName({ project: p.slug, layer, browser }),
-                    testDir,
+                pushTarget({ layer, browser }, {
+                    fullyParallel,
                     // Baselines live with the project (generated specs are per-run and deleted):
                     // projects/<slug>/features/__screenshots__/<pw project>/<platform>/<name>.png
                     snapshotPathTemplate: join(p.root, 'features', '__screenshots__', '{projectName}', '{platform}', '{arg}{ext}'),
                     use: {
-                        ...devices[DEVICE_FOR_BROWSER[browser]],
-                        ...(p.channel && (browser === 'chromium' || browser === 'mobile-chrome')
-                            ? { channel: p.channel }
-                            : {}),
+                        ...browserUse(browser, p.channel),
                         baseURL: cfg.env.ui.baseUrl,
                         testIdAttribute: p.testIdAttribute,
                         viewport: browser.startsWith('mobile') ? undefined : p.screenshots.viewport,
                         ...envUse,
+                        ...evidenceUse,
                         sdods: { project: p.slug, layer, browser },
                     },
                 });
@@ -227,13 +295,16 @@ export function buildRunnerConfig(registry, sel = {}) {
         expect: { timeout: timeouts.expect },
         retries,
         workers,
-        fullyParallel: true,
+        // Each generated project sets its own; this is the fallback for anything added by hand.
+        fullyParallel: first
+            ? runSettings(registry, first.project.slug, first.project, sel.process).fullyParallel
+            : true,
         outputDir: join(runDir, runFiles.output),
         reporter,
         use: {
-            screenshot: 'off',
-            video: 'retain-on-failure',
-            trace: 'on-first-retry',
+            screenshot: first?.project.evidence.screenshot ?? EVIDENCE_DEFAULTS.screenshot,
+            video: first?.project.evidence.video ?? EVIDENCE_DEFAULTS.video,
+            trace: first?.project.evidence.trace ?? EVIDENCE_DEFAULTS.trace,
             actionTimeout: timeouts.action,
             navigationTimeout: timeouts.navigation,
             // Playwright's own `--headed` flag still wins on the CLI; this is what makes the documented
@@ -248,6 +319,66 @@ export function buildRunnerConfig(registry, sel = {}) {
         },
     };
 }
+/**
+ * `retries.byTag` as runner projects.
+ *
+ * Retries are fixed when a test is collected: Playwright takes them from the enclosing
+ * `test.describe.configure` or the project, and offers no runtime setter; bddgen has no hook to
+ * add `@retries:N` to a scenario it did not read from the feature file. What Playwright does
+ * offer is project-level `grep`, matched against the title AND the tags. So each byTag entry
+ * becomes a sibling of the project — same name, so `--project <name>`, reports and dashboards are
+ * unchanged — that greps for the tag and carries its retries, and the base project inverts every
+ * byTag grep. Entries are ordered by retries, highest first, and each sibling also inverts the
+ * ones before it, so a scenario with two such tags runs exactly once, with the larger count.
+ *
+ * Explicit `--retries` on the CLI still overrides every project, these included. A scenario's own
+ * `@retries:N` tag (playwright-bdd) wins over all of it.
+ */
+export function withRetriesByTag(project, byTag) {
+    const entries = Object.entries(byTag)
+        .map(([tag, retries]) => ({ tag: tag.startsWith('@') ? tag : `@${tag}`, retries }))
+        .sort((a, b) => b.retries - a.retries);
+    if (!entries.length)
+        return [project];
+    // Whitespace-delimited: Playwright joins the title path and tags with spaces, so `@flaky`
+    // must not match `@flakyish`. (A scenario TITLE containing the literal tag also matches.)
+    const tagRe = (tag) => new RegExp(`(^|\\s)${tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`);
+    const seen = [];
+    const out = [];
+    for (const { tag, retries } of entries) {
+        const re = tagRe(tag);
+        out.push({
+            ...project,
+            grep: re,
+            ...(seen.length ? { grepInvert: [...seen] } : {}),
+            retries,
+        });
+        seen.push(re);
+    }
+    return [{ ...project, grepInvert: seen }, ...out];
+}
+/**
+ * `fullyParallel` and the setup tier for one project, with a named process taking precedence.
+ * A process that is not defined for this project (a multi-project run) leaves the project's own.
+ */
+function runSettings(registry, slug, project, processName) {
+    const proc = processName
+        ? registry.processesOf(slug).find((x) => x.name === processName)
+        : undefined;
+    return {
+        fullyParallel: proc?.fullyParallel ?? project.fullyParallel,
+        setup: setupTierOf(project, proc),
+    };
+}
+/**
+ * The setup tier a run uses: the process's `setup` (`false` turns it off), else the project's.
+ * Tags are normalised like `--tags`, so `setup: { tags: setup }` means `@setup`.
+ */
+export function setupTierOf(project, proc) {
+    const setup = proc?.setup === false ? undefined : (proc?.setup ?? project.setup);
+    const tags = normalizeTagExpr(setup?.tags);
+    return tags ? { tags } : undefined;
+}
 function parseEnvOverrides() {
     const raw = process.env.SDODS_CLI_OVERRIDES;
     if (!raw)

package/dist/config/tags.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectConfig } from '@sdods/contracts';
+import { type ProjectConfig } from '@sdods/contracts';
 export declare const LAYER_TAGS: readonly ["@ui", "@api", "@hybrid"];
 /** Control tags the runner interprets itself; lint passes them through untouched. */
 export declare const RUNNER_SPECIAL_TAGS: RegExp;
@@ -6,7 +6,11 @@ export declare const RUNNER_SPECIAL_TAGS: RegExp;
 export declare const PLAYWRIGHT_BDD_SPECIAL: RegExp;
 export declare const VALUE_TAG: RegExp;
 export declare const KNOWN_VALUE_TAGS: readonly ["env", "user", "data", "har", "jira", "github", "skip", "title", "flag"];
-export declare const BROWSERS_FOR_SKIP: readonly ["chromium", "firefox", "webkit", "mobile-chrome", "mobile-safari"];
+/**
+ * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser
+ * to `BrowserSchema` is the only edit needed — and the lint message lists the new name for free.
+ */
+export declare const BROWSERS_FOR_SKIP: ("chromium" | "edge" | "firefox" | "webkit" | "mobile-chrome" | "mobile-safari")[];
 export interface TagTaxonomy {
     layers: readonly string[];
     suites: string[];
@@ -24,6 +28,14 @@ export declare function suiteOfTags(tags: readonly string[], suites: readonly st
 export declare function combineTagExpr(layerTag: string, userExpr?: string): string;
 /** `--tags @smoke` shorthand also accepts comma lists ("@smoke,@sanity" → "@smoke or @sanity"). */
 export declare function normalizeTagExpr(input?: string): string | undefined;
+export interface TagExpr {
+    evaluate(tags: readonly string[]): boolean;
+}
+/**
+ * Parse a Cucumber tag expression, or fail as a configuration error (exit 2) that quotes it.
+ * Every command that selects scenarios by tag goes through here so they agree on what matches.
+ */
+export declare function parseTagExpr(expr: string): TagExpr;
 export interface TagGateContext {
     /** `config.env.name` — the environment this run is actually pointed at. */
     env: string;

package/dist/config/tags.js

@@ -1,3 +1,6 @@
+import parseInfix from 'cucumber-tag-expressions';
+import { BrowserSchema } from '@sdods/contracts';
+import { SdodsError } from '../errors.js';
 export const LAYER_TAGS = ['@ui', '@api', '@hybrid'];
 /** Control tags the runner interprets itself; lint passes them through untouched. */
 export const RUNNER_SPECIAL_TAGS = /^@(only|skip|fixme|fail|slow|timeout:\d+|retries:\d+|mode:(parallel|serial|default))$/;
@@ -15,13 +18,11 @@ export const KNOWN_VALUE_TAGS = [
     'title',
     'flag',
 ];
-export const BROWSERS_FOR_SKIP = [
-    'chromium',
-    'firefox',
-    'webkit',
-    'mobile-chrome',
-    'mobile-safari',
-];
+/**
+ * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser
+ * to `BrowserSchema` is the only edit needed — and the lint message lists the new name for free.
+ */
+export const BROWSERS_FOR_SKIP = BrowserSchema.options;
 export function taxonomyFromProject(project) {
     return {
         layers: LAYER_TAGS,
@@ -75,6 +76,25 @@ export function normalizeTagExpr(input) {
         .map((t) => (t.startsWith('@') ? t : `@${t}`));
     return parts.length > 1 ? parts.join(' or ') : parts[0];
 }
+// The package is CommonJS with `exports.default`; ESM interop may hand back the module object.
+const parseInfixFn = (parseInfix.default ??
+    parseInfix);
+/**
+ * Parse a Cucumber tag expression, or fail as a configuration error (exit 2) that quotes it.
+ * Every command that selects scenarios by tag goes through here so they agree on what matches.
+ */
+export function parseTagExpr(expr) {
+    try {
+        const node = parseInfixFn(expr);
+        return { evaluate: (tags) => node.evaluate([...tags]) };
+    }
+    catch (e) {
+        throw new SdodsError('CONFIG_INVALID', `Invalid tag expression "${expr}": ${e.message}`, {
+            hint: 'Combine tags with and / or / not and balanced parentheses, e.g. "@ui and (@smoke or @sanity)".',
+            exitCode: 2,
+        });
+    }
+}
 /**
  * Why this scenario should not run here, or undefined to run it.
  *

package/dist/evidence/index.d.ts

@@ -0,0 +1,3 @@
+export * from './trace-redact.js';
+export { readZip, writeZip, entryContent, isZip, ZipFormatError, type ZipEntry } from './zip.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/evidence/index.js

@@ -0,0 +1,3 @@
+export * from './trace-redact.js';
+export { readZip, writeZip, entryContent, isZip, ZipFormatError } from './zip.js';
+//# sourceMappingURL=index.js.map

package/dist/evidence/trace-redact.d.ts

@@ -0,0 +1,74 @@
+import { type ZipEntry } from './zip.js';
+/**
+ * Strip credentials out of Playwright traces (#101).
+ *
+ * A trace records every request and response header, the context's options (`extraHTTPHeaders`,
+ * `httpCredentials`, `storageState`), every `storageState()` / `addCookies()` call with its result,
+ * DOM snapshots and the arguments of every action. For a project that signs in with pool accounts
+ * that is the session cookie, the `Authorization` bearer and — for Firebase — the long-lived
+ * refresh token in localStorage/IndexedDB.
+ *
+ * What is replaced with `[redacted]`:
+ * - credential headers (`Cookie`, `Set-Cookie`, `Authorization`, `Proxy-Authorization`,
+ *   `X-Api-Key` and similar) wherever a `{ name, value }` header or a header map appears —
+ *   `.network` request/response entries, context options, route and fetch parameters;
+ * - every cookie value, localStorage/sessionStorage value and IndexedDB record;
+ * - `password` / `passphrase` fields (`httpCredentials`, `proxy`, client certificates);
+ * - the value of password inputs in DOM snapshots, and values typed by `fill`/`type` into a field
+ *   whose locator names a password, secret, token or one-time code (best effort).
+ *
+ * Not covered: response and request bodies (`resources/`), page text and screenshots. A redacted
+ * trace is safer to keep, not safe to publish.
+ *
+ * Only `*.trace` and `*.network` entries are rewritten; everything else (sources, screenshots,
+ * resources, stacks) is copied through unchanged, so the trace viewer opens the result as before.
+ */
+export declare const REDACTED = "[redacted]";
+export declare const TRACE_SECRET_HEADER: RegExp;
+/**
+ * Redact one parsed trace event in place. Returns the number of values replaced.
+ *
+ * `typed` carries values redacted from typing actions across the events of one stream, by call id,
+ * so the action's `log` lines (`fill("…")`) lose the value too.
+ */
+export declare function redactTraceEvent(event: unknown, typed?: Map<string, string>): number;
+/** Redact every JSON line of a `.trace` / `.network` entry. Unparseable lines are kept as they are. */
+export declare function redactTraceJsonl(text: string): {
+    text: string;
+    changed: number;
+};
+/** True when the buffer is a zip holding a Playwright trace (or a zip that nests one). */
+export declare function isTraceZip(entries: ZipEntry[]): boolean;
+/**
+ * Redact a trace zip held in memory. Zips nested inside (blob shard reports keep attachments as
+ * `resources/<sha>.zip`) are redacted too. Non-trace zips come back untouched with `trace: false`.
+ */
+export declare function redactTraceZip(buf: Buffer): {
+    buffer: Buffer;
+    changed: number;
+    trace: boolean;
+};
+/** Redact a trace zip on disk in place. Returns values replaced (0 when not a trace). */
+export declare function redactTraceFile(file: string): number;
+/**
+ * Cucumber messages embed each trace as a BASE64 attachment body, and ingest writes `trace.zip`
+ * from those bytes — so the copy in `messages*.ndjson` is redacted as well.
+ */
+export declare function redactMessagesFile(file: string): number;
+export interface RunTraceRedaction {
+    /** trace zips and message files that were rewritten */
+    files: string[];
+    /** values replaced across all of them */
+    values: number;
+    /** files that could not be read or rewritten, with the reason */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * Redact every trace a run left behind: `runner-output/<test>/trace.zip`, the HTML report's copies
+ * under `html-report/data/`, blob shard reports, and the BASE64 bodies in `messages*.ndjson`.
+ */
+export declare function redactRunTraces(runDir: string, maxDepth?: number): RunTraceRedaction;
+//# sourceMappingURL=trace-redact.d.ts.map