@sdods/core 0.2.2 → 0.3.1

package/dist/steps/clock.steps.js

@@ -0,0 +1,73 @@
+import { expect } from '@playwright/test';
+import './params.js';
+import { Given, Then } from '../fixtures/test.js';
+import { render } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+/**
+ * Clock control.
+ *
+ * DESIGN — installing the clock is a SEPARATE step from moving it, and it must
+ * come first. `page.clock.install()` has to run before the page under test
+ * reads `Date.now()`, so a scenario installs the clock, then navigates, then
+ * advances. Folding the two together would produce a step that appears to work
+ * and silently does nothing on an already-loaded page, which is worse than one
+ * that refuses.
+ *
+ * WHAT THIS UNBLOCKS — trials, expiry, scheduled runs and session TTLs. None of
+ * these can be tested by waiting: a 55-minute session TTL is not a thing a
+ * suite can sit through, so without clock control those scenarios are not slow,
+ * they are unwritable.
+ */
+const scopesOf = (apiContext, env) => [apiContext.vars.toObject(), env.vars];
+/** ISO-8601, or a relative offset like "+2 days" / "-30 minutes". */
+export function resolveTime(spec, from) {
+    const rel = /^([+-])\s*(\d+)\s*(second|minute|hour|day|week)s?$/i.exec(spec.trim());
+    if (rel) {
+        const [, sign, amount, unit] = rel;
+        const ms = { second: 1e3, minute: 6e4, hour: 36e5, day: 864e5, week: 6048e5 }[unit.toLowerCase()] ?? 0;
+        const delta = Number(amount) * ms * (sign === '-' ? -1 : 1);
+        return new Date(from.getTime() + delta);
+    }
+    const abs = new Date(spec);
+    if (Number.isNaN(abs.getTime())) {
+        throw new SdodsError('CONFIG_INVALID', `Cannot read "${spec}" as a time.`, {
+            hint: 'Use an ISO-8601 instant (2026-01-31T12:00:00Z) or a relative offset ("+2 days", "-30 minutes").',
+        });
+    }
+    return abs;
+}
+Given('I install a fake clock', async ({ page }) => {
+    await page.clock.install();
+});
+Given('I install a fake clock set to {string}', async ({ page, apiContext, env }, when) => {
+    const at = resolveTime(render(when, ...scopesOf(apiContext, env)), new Date());
+    await page.clock.install({ time: at });
+});
+/**
+ * Jumps the clock without running the timers in between. This is what a trial
+ * expiring "two weeks later" means — and running two weeks of intervals would
+ * hang the test rather than simulate it.
+ */
+Given('the clock jumps to {string}', async ({ page, apiContext, env }, when) => {
+    const at = resolveTime(render(when, ...scopesOf(apiContext, env)), new Date());
+    await page.clock.setFixedTime(at);
+});
+/** Runs timers as it goes, so polling and countdowns actually fire. */
+Given('the clock advances by {string}', async ({ page, apiContext, env }, amount) => {
+    const spec = render(amount, ...scopesOf(apiContext, env)).trim();
+    const normalised = /^[+-]/.test(spec) ? spec : `+${spec}`;
+    const target = resolveTime(normalised, new Date(0));
+    await page.clock.runFor(target.getTime());
+});
+Given('the clock resumes', async ({ page }) => {
+    await page.clock.resume();
+});
+Then('the page clock should read {string}', async ({ page, apiContext, env }, iso) => {
+    const expected = resolveTime(render(iso, ...scopesOf(apiContext, env)), new Date());
+    const actual = await page.evaluate(() => Date.now());
+    // A second of tolerance: the assertion is about which DAY or HOUR the page
+    // believes it is, and demanding millisecond equality would make it flaky for
+    // no benefit.
+    expect(Math.abs(actual - expected.getTime())).toBeLessThan(1000);
+});
+//# sourceMappingURL=clock.steps.js.map

package/dist/steps/data.steps.js

@@ -1,7 +1,11 @@
+import { existsSync, readFileSync } from 'node:fs';
 import './params.js';
 import { Given, When } from '../fixtures/test.js';
+import { tokenFileFor } from '../auth/capture.js';
 import { render } from '../api/template.js';
 import { SdodsError } from '../errors.js';
+import { Logger } from '../logger.js';
+const log = new Logger('data');
 /* ── datasets ─────────────────────────────────────────────────────────── */
 Given('I load dataset {string} row {int}', async ({ data, apiContext }, name, index) => {
     apiContext.vars.setAll(await data.row(name, index));
@@ -41,8 +45,31 @@ Given('I use the user {string} from the pool', async ({ userPool, apiContext, $t
         role: user.role,
     });
 });
-/** API-layer variant: leases the account and exposes its credentials without touching a browser. */
-Given('I use a leased user with role {string} for API calls', async ({ userPool, apiContext, $testInfo }, role) => {
+/**
+ * API-layer variant: leases the account, exposes its credentials as variables,
+ * AND authenticates the API client as that user.
+ *
+ * The authentication half used to be missing, which left the whole role-based
+ * API story unwired. Three seams were dead at once:
+ *
+ *   1. `storageState` is forced to undefined when `sdods.layer === 'api'`
+ *      (fixtures/test.ts) — correct in itself, an API test should not need a
+ *      browser, but it means the `@user:<role>` tag applies no credential here.
+ *   2. This step set variables and performed no authentication.
+ *   3. The strategy's `token()` result was written to
+ *      `<role>-<n>.token.json` by `sdods auth capture` and never read back.
+ *
+ * The net effect was that every API request in a role-tagged scenario went out
+ * anonymous. Against an app that answers 401 the scenario failed loudly, which
+ * is survivable — but against one that answers 200 to anonymous reads, an
+ * authorization scenario passed while proving nothing at all.
+ *
+ * Resolution order: the cached token file (so `sdods auth capture` is
+ * meaningful and one mint is reused across a sharded run), then a live
+ * `token()` call. A strategy with no `token()` leaves auth unset and says so,
+ * rather than silently continuing anonymous.
+ */
+Given('I use a leased user with role {string} for API calls', async ({ userPool, apiContext, auth, config, $testInfo }, role) => {
     const user = await userPool.lease(role, $testInfo.parallelIndex);
     apiContext.vars.setAll({
         username: user.username,
@@ -51,7 +78,28 @@ Given('I use a leased user with role {string} for API calls', async ({ userPool,
         role: user.role,
         ...user.extra,
     });
+    const token = readCachedToken(config, user) ?? (await auth?.token?.({ config, user }));
+    if (token)
+        apiContext.auth = { type: 'bearer', token };
+    else if (auth?.strategy && auth.strategy !== 'none') {
+        log.debug(`auth strategy "${auth.strategy}" provides no token() — API calls for ` +
+            `${user.username} (${role}) use the environment credential.`);
+    }
 });
+/** The token `sdods auth capture` wrote for this user, when it is still there. */
+function readCachedToken(config, user) {
+    const file = tokenFileFor(config, user);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return parsed.token;
+    }
+    catch {
+        // A corrupt cache must not fail the scenario — fall through to a live mint.
+        return undefined;
+    }
+}
 /* ── cleanup ──────────────────────────────────────────────────────────── */
 When('I register cleanup {method} {string}', async ({ data, api, apiContext, env }, method, path) => {
     const rendered = render(path, apiContext.vars.toObject(), env.vars);

package/dist/steps/db.steps.d.ts

@@ -0,0 +1,5 @@
+import './params.js';
+export declare function identifier(kind: string, value: string): string;
+/** `a = 1, b = x` → [['a', '1'], ['b', 'x']]. Values stay parameterised. */
+export declare function parseWhere(clause: string): Array<[string, string]>;
+//# sourceMappingURL=db.steps.d.ts.map

package/dist/steps/db.steps.js

@@ -0,0 +1,105 @@
+import { expect } from '@playwright/test';
+import './params.js';
+import { Then, When } from '../fixtures/test.js';
+import { render } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+/**
+ * Database assertions over the existing Kysely worker fixture.
+ *
+ * WHY — "the UI said 200 and no row was written" is the exact class of defect a
+ * black-box suite cannot see, and the `db` fixture has existed all along with
+ * no step reading it. A far-side check is the only way to catch a silent
+ * success.
+ *
+ * DESIGN — READ ONLY. There is deliberately no step that INSERTs or UPDATEs.
+ * Seeding through the database rather than the application is how a suite comes
+ * to assert against states the product cannot actually produce, and the rows it
+ * writes then outlive the scenario. Seed through the API; assert through here.
+ *
+ * The table and column names a scenario passes are validated against a strict
+ * identifier pattern before they reach the query builder. Kysely parameterises
+ * VALUES, but an identifier is not a parameter — it is interpolated — so a
+ * table name taken from a Gherkin string is an injection point unless it is
+ * checked. Rejecting anything that is not a plain identifier is a smaller
+ * surface than trying to escape it.
+ */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const scopesOf = (apiContext, env) => [apiContext.vars.toObject(), env.vars];
+function requireDb(db) {
+    if (!db) {
+        throw new SdodsError('DB_REQUIRED', 'This scenario needs a database connection.', {
+            hint: 'Declare `db:` in the environment yaml. The db fixture is undefined when no connection is configured, and a db assertion that silently passes without one is worthless.',
+        });
+    }
+    return db;
+}
+export function identifier(kind, value) {
+    if (!IDENTIFIER.test(value)) {
+        throw new SdodsError('CONFIG_INVALID', `"${value}" is not a valid ${kind} name.`, {
+            hint: 'Table and column names are interpolated into SQL, not parameterised, so only plain identifiers are accepted.',
+        });
+    }
+    return value;
+}
+/** `a = 1, b = x` → [['a', '1'], ['b', 'x']]. Values stay parameterised. */
+export function parseWhere(clause) {
+    return clause.split(',').map((part) => {
+        const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+?)\s*$/.exec(part);
+        if (!m) {
+            throw new SdodsError('CONFIG_INVALID', `Cannot read "${part.trim()}" as a condition.`, {
+                hint: 'Write conditions as `column = value`, separated by commas.',
+            });
+        }
+        return [identifier('column', m[1]), m[2].replace(/^["']|["']$/g, '')];
+    });
+}
+async function rowsWhere(db, table, clause) {
+    const kysely = db;
+    let q = kysely.selectFrom(identifier('table', table)).selectAll();
+    for (const [col, val] of parseWhere(clause))
+        q = q.where(col, '=', val);
+    return q.execute();
+}
+/* ── assertions ───────────────────────────────────────────────────────── */
+Then('the {string} table should have {int} row(s) where {string}', async ({ db, apiContext, env }, table, count, clause) => {
+    const scopes = scopesOf(apiContext, env);
+    const rows = await rowsWhere(requireDb(db), render(table, ...scopes), render(clause, ...scopes));
+    expect(rows, `${table} where ${clause}`).toHaveLength(count);
+});
+Then('the {string} table should have a row where {string}', async ({ db, apiContext, env }, table, clause) => {
+    const scopes = scopesOf(apiContext, env);
+    const rows = await rowsWhere(requireDb(db), render(table, ...scopes), render(clause, ...scopes));
+    expect(rows.length, `${table} where ${clause}`).toBeGreaterThan(0);
+});
+Then('the {string} table should have no row where {string}', async ({ db, apiContext, env }, table, clause) => {
+    const scopes = scopesOf(apiContext, env);
+    const rows = await rowsWhere(requireDb(db), render(table, ...scopes), render(clause, ...scopes));
+    expect(rows, `${table} where ${clause}`).toHaveLength(0);
+});
+Then('the {string} column of the row where {string} in {string} should be {string}', async ({ db, apiContext, env }, column, clause, table, value) => {
+    const scopes = scopesOf(apiContext, env);
+    const rows = await rowsWhere(requireDb(db), render(table, ...scopes), render(clause, ...scopes));
+    if (rows.length !== 1) {
+        throw new SdodsError('CONFIG_INVALID', `Expected exactly one row in ${table} where ${clause}, found ${rows.length}.`, {
+            hint: 'Narrow the condition. Asserting a column across several rows hides which one matched.',
+        });
+    }
+    expect(String(rows[0][identifier('column', render(column, ...scopes))])).toBe(render(value, ...scopes));
+});
+/**
+ * Polling variant. A write that the API acknowledges is often applied
+ * asynchronously, and the alternative to this step is a sleep — which is either
+ * too short (flaky) or too long (slow), and never right.
+ */
+When('I wait for the {string} table to have a row where {string}', async ({ db, apiContext, env }, table, clause) => {
+    const scopes = scopesOf(apiContext, env);
+    const handle = requireDb(db);
+    const t = render(table, ...scopes);
+    const c = render(clause, ...scopes);
+    await expect
+        .poll(async () => (await rowsWhere(handle, t, c)).length, {
+        message: `${t} never got a row where ${c}`,
+    })
+        .toBeGreaterThan(0);
+});
+//# sourceMappingURL=db.steps.js.map

package/dist/steps/dom.steps.d.ts

@@ -0,0 +1,2 @@
+import './params.js';
+//# sourceMappingURL=dom.steps.d.ts.map