@sdods/core 0.2.2 → 0.3.1

package/dist/auth/index.js

@@ -1,5 +1,6 @@
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { SdodsError } from '../errors.js';
 /**
  * Define the project's auth strategy. `form` uses `auth.form` selectors from the project yaml
  * unless a custom `login` is provided.
@@ -31,7 +32,16 @@ export function defineAuth(def) {
         case 'token':
             return {
                 strategy: 'token',
-                login: async () => undefined,
+                // A `token` project can call the API and has NO browser session. Returning `undefined`
+                // here let a @ui scenario run signed-out and then fail on an assertion about the page,
+                // which reads as a product defect rather than as a misconfigured project. Fail where the
+                // cause is, and say what to do instead.
+                login: async () => {
+                    throw new SdodsError('NOT_SUPPORTED', 'The `token` auth strategy provides an API credential, not a browser session.', {
+                        hint: 'Use `strategy: "custom"` with a `login` that performs the sign-in and returns a storageState, or restrict these scenarios to the @api layer.',
+                        exitCode: 2,
+                    });
+                },
                 token: def.token,
             };
         case 'oauth-client-credentials':
@@ -63,7 +73,18 @@ export function defineAuth(def) {
                 },
             };
         case 'sso':
-            return { strategy: 'sso', login: async () => undefined };
+            return {
+                strategy: 'sso',
+                // `sso` was a stub: it returned no session and threw nothing, so every scenario under it
+                // ran unauthenticated and silently. There is no generic SSO sign-in to implement — the
+                // flow is provider-specific — so the honest behaviour is to refuse and name the seam.
+                login: async () => {
+                    throw new SdodsError('NOT_SUPPORTED', 'The `sso` auth strategy is a placeholder: it performs no sign-in.', {
+                        hint: 'SSO flows are provider-specific. Use `strategy: "custom"` with a `login` that drives your identity provider, or capture a session once with `sdods auth capture --interactive`.',
+                        exitCode: 2,
+                    });
+                },
+            };
         case 'custom':
             return { strategy: 'custom', login: def.login, token: def.token };
     }

package/dist/config/resolve.d.ts

@@ -50,6 +50,19 @@ export interface ResolvedConfig {
     sources: {
         dotenvFiles: string[];
     };
+    /**
+     * The resolved `${VAR}` scope: the dotenv layer merged under `process.env`.
+     *
+     * Exposed because `loadDotEnvLayer` deliberately does NOT mutate `process.env`
+     * (doing so would silently outrank the process layer), so anything that
+     * interpolates `${VAR}` outside the config tree — dataset rows, most of all —
+     * cannot reach the values in `.env.<env>` unless it is handed this. Without
+     * it, the documented pattern of keeping passwords in `.env.<env>` and
+     * referencing them from `data/**\/users.csv` resolves to the literal string
+     * `${TEST_MEMBER_PASSWORD}`, and the failure surfaces far away as a provider
+     * rejecting the credential.
+     */
+    vars: Record<string, string | undefined>;
 }
 export interface ResolveOptions {
     rootDir: string;

package/dist/config/resolve.js

@@ -162,6 +162,7 @@ export function resolveConfig(opts) {
         runtime: rt,
         provenance: Object.fromEntries(prov.byPath),
         sources: { dotenvFiles: dotenv.files },
+        vars,
     };
 }
 function markAll(obj, prov, layer, prefix) {

package/dist/config/runner.js

@@ -3,7 +3,7 @@ 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 { coreStepsGlob } from '../steps/glob.js';
+import { coreStepsPatterns } from '../steps/glob.js';
 import { combineTagExpr, normalizeTagExpr } from './tags.js';
 const DEVICE_FOR_BROWSER = {
     chromium: 'Desktop Chrome',
@@ -121,7 +121,7 @@ export function buildRunnerConfig(registry, sel = {}) {
             const testDir = defineBddConfig({
                 features: `${toPosix(p.root)}/features/**/*.feature`,
                 steps: [
-                    coreStepsGlob(),
+                    ...coreStepsPatterns(cfg.project.steps?.core?.exclude ?? []),
                     `${toPosix(p.root)}/steps/**/*.ts`,
                     `${toPosix(p.root)}/pages/**/*.ts`,
                 ],

package/dist/config/tags.d.ts

@@ -5,7 +5,7 @@ export declare const RUNNER_SPECIAL_TAGS: RegExp;
 /** @deprecated Use {@link RUNNER_SPECIAL_TAGS}. Removed in the next minor. */
 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"];
+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"];
 export interface TagTaxonomy {
     layers: readonly string[];
@@ -24,4 +24,32 @@ 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 TagGateContext {
+    /** `config.env.name` — the environment this run is actually pointed at. */
+    env: string;
+    /** Browser of the current Playwright project, when there is one. */
+    browser?: string;
+    /**
+     * Feature flags baked into the environment under test. Undefined means "not
+     * known", which is treated as "do not gate" — an unknown flag list must not
+     * silently skip a suite.
+     */
+    flags?: readonly string[];
+    /** Whether `@quarantine` scenarios run. Defaults to skipping them. */
+    quarantine?: 'run' | 'skip';
+}
+/**
+ * Why this scenario should not run here, or undefined to run it.
+ *
+ * Four tags were validated at LINT time and had no runtime path at all, which
+ * is the worst arrangement available: the tag reads as a control, the linter
+ * confirms it is spelled correctly, and the runner ignores it. A project can
+ * carry hundreds of `@env:` tags and still send every one of them at
+ * production.
+ *
+ * Kept a pure function, separate from the fixture that calls it, because the
+ * property that matters — "a tag that excludes this environment MUST skip" —
+ * should be testable without a browser, a config or a Playwright runner.
+ */
+export declare function scenarioSkipReason(tags: readonly string[], ctx: TagGateContext): string | undefined;
 //# sourceMappingURL=tags.d.ts.map

package/dist/config/tags.js

@@ -13,6 +13,7 @@ export const KNOWN_VALUE_TAGS = [
     'github',
     'skip',
     'title',
+    'flag',
 ];
 export const BROWSERS_FOR_SKIP = [
     'chromium',
@@ -74,4 +75,49 @@ export function normalizeTagExpr(input) {
         .map((t) => (t.startsWith('@') ? t : `@${t}`));
     return parts.length > 1 ? parts.join(' or ') : parts[0];
 }
+/**
+ * Why this scenario should not run here, or undefined to run it.
+ *
+ * Four tags were validated at LINT time and had no runtime path at all, which
+ * is the worst arrangement available: the tag reads as a control, the linter
+ * confirms it is spelled correctly, and the runner ignores it. A project can
+ * carry hundreds of `@env:` tags and still send every one of them at
+ * production.
+ *
+ * Kept a pure function, separate from the fixture that calls it, because the
+ * property that matters — "a tag that excludes this environment MUST skip" —
+ * should be testable without a browser, a config or a Playwright runner.
+ */
+export function scenarioSkipReason(tags, ctx) {
+    // @env:<name> — an ALLOW list. Tagging any environment excludes every other
+    // one; tagging none leaves the scenario unrestricted.
+    const envs = parseTagValues(tags, 'env');
+    if (envs.length && !envs.includes(ctx.env)) {
+        return `@env:${envs.join(', @env:')} — this run is on "${ctx.env}"`;
+    }
+    // @skip:<browser> — a DENY list, and the opposite direction on purpose: it
+    // names what must not run rather than what may.
+    if (ctx.browser) {
+        const skipped = parseTagValues(tags, 'skip');
+        if (skipped.includes(ctx.browser))
+            return `@skip:${ctx.browser}`;
+    }
+    // @quarantine — known-flaky, excluded unless explicitly asked for. Every
+    // recipe was excluding these by hand in its tag expression, which is a
+    // per-recipe list that drifts and that nobody can audit centrally.
+    if (tags.includes('@quarantine') && (ctx.quarantine ?? 'skip') === 'skip') {
+        return '@quarantine — set SDODS_QUARANTINE=run to include quarantined scenarios';
+    }
+    // @flag:<name> — the scenario needs a feature flag that this build may not
+    // carry. Flags are usually baked at build time, so a test cannot turn one on;
+    // it can only discover which way the build went and decline to assert.
+    if (ctx.flags) {
+        const required = parseTagValues(tags, 'flag');
+        const missing = required.filter((f) => !ctx.flags.includes(f));
+        if (missing.length) {
+            return `@flag:${missing.join(', @flag:')} — not enabled in "${ctx.env}"`;
+        }
+    }
+    return undefined;
+}
 //# sourceMappingURL=tags.js.map

package/dist/data/provider.js

@@ -28,7 +28,11 @@ export class CompositeDataProvider {
                 hint: `Known datasets: ${Object.keys(this.config.project.data.sources).join(', ') || '(none)'}. Add it under data.sources in sdods.project.yaml.`,
             });
         }
-        return (await loadFileSource(this.config, spec, this.opts.vars ?? process.env));
+        // `config.vars` is the dotenv layer merged under process.env — the same
+        // scope the yaml was interpolated with. Falling back to bare `process.env`
+        // here meant a `${VAR}` in a dataset could only ever resolve from the
+        // shell, never from the `.env.<env>` file SDODS itself loaded.
+        return (await loadFileSource(this.config, spec, this.opts.vars ?? this.config.vars ?? process.env));
     }
     async row(dataset, index) {
         const rows = await this.load(dataset);

package/dist/data/user-pool.js

@@ -138,8 +138,30 @@ export class FileUserPool {
                 hint: `Roles present: ${[...new Set(rows.map((r) => String(r[pool.roleColumn])))].join(', ')}.`,
             });
         }
+        // A shared pool hands out an account without acquiring a lease at all.
+        // Deterministic by worker index, so two workers on the same role get
+        // different accounts when the pool has them and the same one when it does
+        // not — which is the point: sharing is what makes a single-account role
+        // usable by a parallel read-only suite.
+        if (pool.mode === 'shared') {
+            const picked = candidates[_parallelIndex % candidates.length];
+            const id = String(picked.r.id ?? picked.r.username ?? picked.index);
+            const user = {
+                id,
+                username: String(picked.r.username ?? id),
+                password: String(picked.r.password ?? ''),
+                role,
+                index: picked.index,
+                extra: picked.r,
+                leaseKey: '',
+                owner: this.opts.owner,
+            };
+            this.leased.set(role, user);
+            this.log.debug(`shared ${user.username} (${role}) for ${this.opts.owner}`);
+            return user;
+        }
         const ttl = pool.leaseTtlMs;
-        const waitMs = this.opts.waitMs ?? 30_000;
+        const waitMs = this.opts.waitMs ?? pool.waitMs;
         const started = Date.now();
         while (true) {
             for (const { r, index } of candidates) {
@@ -163,14 +185,24 @@ export class FileUserPool {
             if (Date.now() - started > waitMs) {
                 const owners = await this.store.owners();
                 throw new SdodsError('USER_POOL_EXHAUSTED', `All ${candidates.length} user(s) with role "${role}" are leased.`, {
-                    hint: `Owners: ${JSON.stringify(owners)}. Increase env.users.poolSize, add users, or lower --workers.`,
+                    hint: `Owners: ${JSON.stringify(owners)}. Waited ${Math.round(waitMs / 1000)}s. ` +
+                        `Four ways out, in the order worth trying: (1) if these scenarios do not ` +
+                        `mutate user-scoped state, set data.userPool.mode: shared — one account ` +
+                        `then serves every worker, which is what a read-only suite needs; ` +
+                        `(2) add more accounts with role "${role}" to dataset "${pool.dataset}"; ` +
+                        `(3) raise data.userPool.waitMs (currently ${waitMs}ms); (4) lower --workers. ` +
+                        `Note env.users.poolSize slices the dataset BEFORE role filtering, so a ` +
+                        `small value can starve a role on its own.`,
                 });
             }
             await new Promise((r) => setTimeout(r, 500));
         }
     }
     async release(user) {
-        await this.store.release(user.leaseKey, this.opts.owner);
+        // A shared user holds no lease (leaseKey is empty). Releasing it would be at
+        // best a no-op and at worst a release of another worker's row.
+        if (user.leaseKey)
+            await this.store.release(user.leaseKey, this.opts.owner);
         this.leased.delete(user.role);
     }
     async releaseAll() {

package/dist/fixtures/api-context.d.ts

@@ -5,6 +5,19 @@ export declare class ApiContext {
     readonly headers: Map<string, string>;
     readonly query: Map<string, string>;
     readonly history: ApiSnapshot[];
+    /**
+     * Scenario-level auth override.
+     *
+     * Three states, and the difference between the last two is load-bearing:
+     *   a value   use this credential
+     *   undefined UNSET — fall back to the environment's `api.auth`
+     *   null      explicitly NONE — send the request unauthenticated
+     *
+     * Before this distinction existed, `I use no authentication` assigned
+     * `undefined` and therefore fell straight back to the environment credential,
+     * silently authenticating the very request the scenario was asserting is
+     * refused. Any suite whose env declared `api.auth` had a no-op step.
+     */
     auth: {
         type: 'bearer';
         token: string;
@@ -16,7 +29,7 @@ export declare class ApiContext {
         type: 'header';
         name: string;
         value: string;
-    } | undefined;
+    } | null | undefined;
     /** step index → number of calls made during that step (for attachment numbering) */
     readonly callsByStep: Map<number, number>;
     get lastResponse(): ApiSnapshot['response'] | undefined;

package/dist/fixtures/api-context.js

@@ -4,6 +4,19 @@ export class ApiContext {
     headers = new Map();
     query = new Map();
     history = [];
+    /**
+     * Scenario-level auth override.
+     *
+     * Three states, and the difference between the last two is load-bearing:
+     *   a value   use this credential
+     *   undefined UNSET — fall back to the environment's `api.auth`
+     *   null      explicitly NONE — send the request unauthenticated
+     *
+     * Before this distinction existed, `I use no authentication` assigned
+     * `undefined` and therefore fell straight back to the environment credential,
+     * silently authenticating the very request the scenario was asserting is
+     * refused. Any suite whose env declared `api.auth` had a no-op step.
+     */
     auth;
     /** step index → number of calls made during that step (for attachment numbering) */
     callsByStep = new Map();

package/dist/fixtures/scenario.js

@@ -37,10 +37,7 @@ export class ScenarioMeta {
             pickleLine: init.pickleLine,
             exampleIndex: null,
             tags,
-            // `featureUri`, not `init.featureUri`: playwright-bdd hands us a repo-root-relative path,
-            // and moduleForFeature resolves its argument against project.root, so passing the raw
-            // value yields projects/<slug>/projects/<slug>/... and matches no module.
-            module: moduleForFeature(config.project, featureUri)?.name,
+            module: moduleForFeature(config.project, init.featureUri)?.name,
             process: process.env.SDODS_PROCESS || undefined,
             retry: testInfo.retry,
             workerIndex: testInfo.workerIndex,

package/dist/fixtures/test.js

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { test as base, createBdd } from 'playwright-bdd';
 import { ProjectRegistry } from '../config/registry.js';
-import { parseTagValue } from '../config/tags.js';
+import { parseTagValue, scenarioSkipReason } from '../config/tags.js';
 import { noopAuth } from '../auth/index.js';
 import { ApiClient } from '../api/client.js';
 import { CompositeDataProvider } from '../data/provider.js';
@@ -89,6 +89,47 @@ export const test = base.extend({
         { scope: 'worker' },
     ],
     // ── test scope ──────────────────────────────────────────────────────────
+    /**
+     * Declared FIRST in test scope, and automatic, so it decides before anything
+     * expensive happens — before a pool account is leased, before a browser
+     * context is built, before a session is minted.
+     *
+     * `@env:`, `@skip:<browser>` and `@flag:` were validated at LINT time and had
+     * no runtime path whatsoever. That is the worst arrangement available: the
+     * tag reads as a control, the linter confirms it is spelled correctly, and
+     * the runner ignores it — so a project can carry hundreds of `@env:` tags and
+     * still point every one of them at production. `@quarantine` was worse still:
+     * it was not a tag this framework knew at all, and every recipe excluded it
+     * by hand in a tag expression that drifts and that nobody can audit.
+     */
+    $sdodsTagGate: [
+        async ({ config, $tags }, use, testInfo) => {
+            const features = config.env.vars?.features;
+            const reason = scenarioSkipReason($tags, {
+                env: config.env.name,
+                browser: testInfo.project.use?.browserName,
+                // Only gate on flags when the environment actually declares them.
+                // An absent list means "not known", and an unknown list must never
+                // silently skip a suite.
+                flags: typeof features === 'string'
+                    ? features
+                        .split(',')
+                        .map((f) => f.trim())
+                        .filter(Boolean)
+                    : undefined,
+                quarantine: process.env.SDODS_QUARANTINE === 'run' ? 'run' : 'skip',
+            });
+            if (reason) {
+                // Recorded as an annotation as well as a skip reason: a run report that
+                // says "skipped" without saying why is the thing that let 175 parked
+                // scenarios go unnoticed.
+                testInfo.annotations.push({ type: 'sdods:skipped', description: reason });
+                testInfo.skip(true, reason);
+            }
+            await use();
+        },
+        { auto: true },
+    ],
     scenario: async ({ config, sdods, $bddContext, $tags }, use, testInfo) => {
         const meta = new ScenarioMeta({
             config,

package/dist/fixtures/types.d.ts

@@ -46,5 +46,7 @@ export interface TestFixtures {
     heal: Healer;
     /** auto fixture: pushes identity annotations */
     $sdodsAnnotations: void;
+    /** auto fixture: applies @env:, @skip:<browser>, @quarantine and @flag: */
+    $sdodsTagGate: void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/index.d.ts

@@ -12,6 +12,6 @@ export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';
 export { ScenarioMeta } from './fixtures/scenario.js';
 export type { TestFixtures, WorkerFixtures, SdodsOption } from './fixtures/types.js';
-export { coreStepsGlob, coreStepsDir } from './steps/glob.js';
+export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,6 +11,6 @@ export { BasePage } from './pages/base-page.js';
 export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';
 export { ScenarioMeta } from './fixtures/scenario.js';
-export { coreStepsGlob, coreStepsDir } from './steps/glob.js';
+export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
 //# sourceMappingURL=index.js.map

package/dist/reporters/dashboard.d.ts

@@ -1,4 +1,21 @@
 import type { FullConfig, FullResult, Reporter, Suite, TestCase, TestResult } from '@playwright/test/reporter';
+interface Entry {
+    id: string;
+    title: string;
+    fullTitle: string;
+    status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted';
+    outcome: 'expected' | 'unexpected' | 'flaky' | 'skipped';
+    duration: number;
+    error?: string;
+    retries: number;
+    projectName: string;
+    layer: string;
+    browser: string;
+    tags: string[];
+    file: string;
+    heals: number;
+    fingerprint?: string;
+}
 export interface DashboardOptions {
     outputDir?: string;
     title?: string;
@@ -20,4 +37,73 @@ export default class DashboardReporter implements Reporter {
     onEnd(_result: FullResult): Promise<void>;
     printsToStdio(): boolean;
 }
+export declare function errorSignature(error: string | undefined): string;
+interface Group {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped?: number;
+    flaky?: number;
+}
+export interface Metrics {
+    title: string;
+    generatedAt: string;
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        timedOut: number;
+        flaky: number;
+        healed: number;
+        durationMs: number;
+        workers: number;
+    };
+    clusters: {
+        signature: string;
+        count: number;
+        titles: string[];
+    }[];
+    byRole: Record<string, Group>;
+    slowest: Entry[];
+    byProject: Record<string, Group>;
+    byLayer: Record<string, Group>;
+    byBrowser: Record<string, Group>;
+    byTag: Record<string, Group>;
+    failed: {
+        fingerprint?: string;
+        title: string;
+        runnerProject: string;
+        error?: string;
+    }[];
+    flaky: {
+        fingerprint?: string;
+        title: string;
+        runnerProject: string;
+    }[];
+    tests: Entry[];
+}
+/**
+ * The dashboard is a DECISION surface, not a report.
+ *
+ * Every run ends with someone asking one of four questions, and the layout answers
+ * them in the order they get asked:
+ *
+ *   1. Can I ship?            -> the verdict line, in words, before any number
+ *   2. What do I fix first?   -> failures CLUSTERED by error signature, because
+ *                                twelve scenarios failing on one broken selector
+ *                                is one problem and a list of twelve reads as twelve
+ *   3. Is it real or flaky?   -> flake, retry and heal counts sit beside the verdict,
+ *                                not in a footer
+ *   4. Do I believe this run? -> skipped and healed are shown as WARNINGS, never
+ *                                folded into a pass rate. A suite that skipped a
+ *                                third of itself is not 100% green, and a healed
+ *                                locator means the application's DOM moved under us
+ *
+ * The role matrix is the one view a general-purpose reporter never has: when
+ * `@user:viewer` fails and `@user:admin` passes, that is a permissions regression,
+ * and it is invisible in any total.
+ */
+export declare function renderHtml(m: Metrics): string;
+export {};
 //# sourceMappingURL=dashboard.d.ts.map