@sdods/core 0.3.2 → 0.5.1

package/dist/steps/clock.steps.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Given, Then } from '../fixtures/test.js';
-import { render } from '../api/template.js';
+import { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 /**
  * Clock control.
@@ -40,7 +40,7 @@ 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());
+    const at = resolveTime(renderStrict(when, ...scopesOf(apiContext, env)), new Date());
     await page.clock.install({ time: at });
 });
 /**
@@ -49,12 +49,12 @@ Given('I install a fake clock set to {string}', async ({ page, apiContext, env }
  * 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());
+    const at = resolveTime(renderStrict(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 spec = renderStrict(amount, ...scopesOf(apiContext, env)).trim();
     const normalised = /^[+-]/.test(spec) ? spec : `+${spec}`;
     const target = resolveTime(normalised, new Date(0));
     await page.clock.runFor(target.getTime());
@@ -63,7 +63,7 @@ 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 expected = resolveTime(renderStrict(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

package/dist/steps/data.steps.js

@@ -2,7 +2,7 @@ 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 { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 const log = new Logger('data');
@@ -29,6 +29,7 @@ Given('I use a leased user with role {string}', async ({ userPool, authCache, au
         role: user.role,
         ...user.extra,
     });
+    LEASED.set(apiContext, user);
     if (sdods.layer !== 'api')
         await authCache.apply({ context, page, user, auth, browser });
 });
@@ -44,6 +45,7 @@ Given('I use the user {string} from the pool', async ({ userPool, apiContext, $t
         userId: user.id,
         role: user.role,
     });
+    LEASED.set(apiContext, user);
 });
 /**
  * API-layer variant: leases the account, exposes its credentials as variables,
@@ -68,6 +70,18 @@ Given('I use the user {string} from the pool', async ({ userPool, apiContext, $t
  * 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.
+ *
+ * Attaching the token is itself a choice of credential class, though, and it
+ * must not be made behind the scenario's back (#87). A `custom` strategy's
+ * `token()` can mint a personal API key for an app whose scenarios also sign
+ * in with a session; attached silently, such a scenario sends BOTH, and "a key
+ * is refused on a session-only route" passes on whichever one the server reads
+ * first. So `auth.apiToken` decides: `implicit` attaches here, `explicit` only
+ * leases and the scenario says `I authenticate the API with the leased user's
+ * token`. Unset, `custom` is explicit and every other strategy keeps the
+ * implicit behaviour #18 introduced — for `token` and
+ * `oauth-client-credentials` the token is the only credential there is.
+ * Either way the attached credential is logged at info.
  */
 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);
@@ -78,17 +92,56 @@ 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 };
+    LEASED.set(apiContext, user);
+    if (apiTokenMode(config, auth) === 'explicit') {
+        log.info(`leased ${user.username} (${role}) for API calls; no credential attached ` +
+            `(auth.apiToken: explicit). Add "I authenticate the API with the leased user's token" to send its token.`);
+        return;
+    }
+    const found = await leasedUserToken(config, auth, user);
+    if (found) {
+        apiContext.auth = { type: 'bearer', token: found.token };
+        log.info(`API calls authenticate as ${user.username} (${role}): bearer token from ${found.source}.`);
+    }
     else if (auth?.strategy && auth.strategy !== 'none') {
-        log.debug(`auth strategy "${auth.strategy}" provides no token() — API calls for ` +
+        log.info(`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) {
+Given("I authenticate the API with the leased user's token", async ({ apiContext, auth, config }) => {
+    const user = LEASED.get(apiContext);
+    if (!user) {
+        throw new SdodsError('AUTH_FAILED', 'No user has been leased in this scenario yet.', {
+            hint: 'Lease one first with `Given I use a leased user with role "<role>" for API calls` (or `I use a leased user with role "<role>"`).',
+        });
+    }
+    const found = await leasedUserToken(config, auth, user);
+    if (!found) {
+        throw new SdodsError('AUTH_FAILED', `No API token for ${user.username} (${user.role}): no cached token file and the "${auth?.strategy ?? 'none'}" auth strategy's token() returned none.`, {
+            hint: `Run \`sdods auth capture --user ${user.role}\` to cache one, or implement token() in the project's defineAuth.`,
+        });
+    }
+    apiContext.auth = { type: 'bearer', token: found.token };
+    log.info(`API calls authenticate as ${user.username} (${user.role}): bearer token from ${found.source}.`);
+});
+/** The user the scenario leased, so the explicit token step authenticates as that same account. */
+const LEASED = new WeakMap();
+function apiTokenMode(config, auth) {
+    return config.project.auth?.apiToken ?? (auth?.strategy === 'custom' ? 'explicit' : 'implicit');
+}
+/** The cached `sdods auth capture` token, else a live `token()` — with where it came from. */
+async function leasedUserToken(config, auth, user) {
     const file = tokenFileFor(config, user);
+    const cached = readCachedToken(file);
+    if (cached)
+        return { token: cached, source: `cached token file ${file}` };
+    const minted = await auth?.token?.({ config, user });
+    return minted
+        ? { token: minted, source: `the "${auth?.strategy}" strategy's token()` }
+        : undefined;
+}
+/** The token `sdods auth capture` wrote for this user, when it is still there. */
+function readCachedToken(file) {
     if (!existsSync(file))
         return undefined;
     try {
@@ -102,7 +155,7 @@ function readCachedToken(config, user) {
 }
 /* ── cleanup ──────────────────────────────────────────────────────────── */
 When('I register cleanup {method} {string}', async ({ data, api, apiContext, env }, method, path) => {
-    const rendered = render(path, apiContext.vars.toObject(), env.vars);
+    const rendered = renderStrict(path, apiContext.vars.toObject(), env.vars);
     data.registerCleanup(async () => {
         await api.send(method, rendered, { silent: true });
     }, `${method} ${rendered}`);

package/dist/steps/db.steps.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Then, When } from '../fixtures/test.js';
-import { render } from '../api/template.js';
+import { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 /**
  * Database assertions over the existing Kysely worker fixture.
@@ -63,28 +63,28 @@ async function rowsWhere(db, table, clause) {
 /* ── 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));
+    const rows = await rowsWhere(requireDb(db), renderStrict(table, ...scopes), renderStrict(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));
+    const rows = await rowsWhere(requireDb(db), renderStrict(table, ...scopes), renderStrict(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));
+    const rows = await rowsWhere(requireDb(db), renderStrict(table, ...scopes), renderStrict(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));
+    const rows = await rowsWhere(requireDb(db), renderStrict(table, ...scopes), renderStrict(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));
+    expect(String(rows[0][identifier('column', renderStrict(column, ...scopes))])).toBe(renderStrict(value, ...scopes));
 });
 /**
  * Polling variant. A write that the API acknowledges is often applied
@@ -94,8 +94,8 @@ Then('the {string} column of the row where {string} in {string} should be {strin
 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);
+    const t = renderStrict(table, ...scopes);
+    const c = renderStrict(clause, ...scopes);
     await expect
         .poll(async () => (await rowsWhere(handle, t, c)).length, {
         message: `${t} never got a row where ${c}`,

package/dist/steps/dom.steps.js

@@ -1,19 +1,19 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Then, When } from '../fixtures/test.js';
-import { render } from '../api/template.js';
+import { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 /**
  * DOM assertions the rest of the library cannot express.
  *
- * The library ships exactly one negative UI step (`I should not see the text`), so the deny
+ * Before this file the library's only negative UI step was `I should not see the text`, so the deny
  * direction of an authorisation scenario — the only direction worth asserting against a
  * default-allow policy — is unwritable. These steps close that, plus the ordinal, counting,
  * focus and overlay vocabulary that a real onboarding had to hand-write.
  *
  * Two conventions hold throughout this file, both of them load-bearing:
  *
- * 1. EVERY string argument goes through `render()`, ids and role names included. A step that
+ * 1. EVERY string argument goes through `renderStrict()`, ids and role names included. A step that
  *    silently drops `{{vars}}` fails much later, in a scenario that looks unrelated; rendering a
  *    string with no placeholder in it is a no-op, so there is no cost to doing it everywhere.
  *
@@ -164,24 +164,24 @@ function bag(key) {
 // Proves the element is not on screen. Passes when it is absent too, because "a user cannot see
 // it" is the invariant — use the "should not exist" form when the DOM node itself is the point.
 Then('the element with test id {string} should not be visible', async ({ page, apiContext, env }, id) => {
-    await expect(page.getByTestId(render(id, ...scopesOf(apiContext, env)))).toBeHidden();
+    await expect(page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env)))).toBeHidden();
 });
 // Proves the node was never rendered — not merely hidden with CSS. The distinction is the point of
 // a deny: a control the server refused to send is a different posture from one the client chose
 // not to paint, which is one CSS toggle or one devtools edit away from being usable.
 Then('the element with test id {string} should not exist', async ({ page, apiContext, env }, id) => {
-    await expect(page.getByTestId(render(id, ...scopesOf(apiContext, env)))).toHaveCount(0);
+    await expect(page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env)))).toHaveCount(0);
 });
 // Proves a named control is not on screen — the deny half of `the {string} {role} should be
 // visible`, which had no counterpart.
 Then('the {string} {role} should not be visible', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.getByRole(role, { name: n })).toBeHidden();
 });
 // Proves the app rendered no such control at all. Distinct from "not visible": this is what an
 // authorisation scenario wants when the claim is that the affordance was never offered.
 Then('no {string} {role} should exist', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.getByRole(role, { name: n })).toHaveCount(0);
 });
 // Proves the absence is the SETTLED state, not the loading state. This is the trap that makes
@@ -190,7 +190,7 @@ Then('no {string} {role} should exist', async ({ page, apiContext, env }, name,
 // passes for everyone as long as it lands first. Holding it across a window outlives the fetch.
 Then('the {string} {role} should stay absent for {int} seconds', async ({ page, apiContext, env }, name, role, seconds) => {
     assertPositiveDuration(seconds);
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const locator = page.getByRole(role, { name: n });
     const deadline = Date.now() + seconds * 1000;
     do {
@@ -205,7 +205,7 @@ Then('the {string} {role} should stay absent for {int} seconds', async ({ page,
 // placeholder, a title or alt. `I should see the text` resolves through `getByText`, which reads
 // text nodes only, so a value prefilled into a field is invisible to it.
 Then('the text {string} should appear anywhere on the page', async ({ page, apiContext, env }, text) => {
-    const wanted = render(text, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(text, ...scopesOf(apiContext, env));
     await expect
         .poll(async () => readableText(page), { message: `page never rendered "${wanted}"` })
         .toContain(wanted);
@@ -215,7 +215,7 @@ Then('the text {string} should appear anywhere on the page', async ({ page, apiC
 // The blank-page guard is the point: on a surface that rendered nothing this check would pass for
 // every string in existence, which is the vacuous pass this library refuses to ship.
 Then('the text {string} should not appear anywhere on the page', async ({ page, apiContext, env }, text) => {
-    const unwanted = render(text, ...scopesOf(apiContext, env));
+    const unwanted = renderStrict(text, ...scopesOf(apiContext, env));
     const haystack = await readableText(page);
     if (haystack.length === 0) {
         throw new SdodsError('RUN_FAILED', 'The page has rendered no readable text at all.', {
@@ -228,14 +228,14 @@ Then('the text {string} should not appear anywhere on the page', async ({ page,
 // Proves the control is offered AND actionable. Healed, on the same terms as the built-in
 // visibility assertion — this is the allow direction. The deny direction below is not healed.
 Then('the {string} {role} should be enabled', async ({ page, heal, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const locator = await heal.resolve(page.getByRole(role, { name: n }), { role: role, name: n, text: n, description: `${role} "${n}"` }, 'assert');
     await expect(locator).toBeEnabled();
 });
 // Proves the control is rendered but refuses to act. NOT healed, deliberately: this is a deny
 // assertion, and healing onto a different, disabled element would fabricate the pass.
 Then('the {string} {role} should be disabled', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.getByRole(role, { name: n })).toBeDisabled();
 });
 // Proves the disabled state is the settled one. `toBeDisabled()` retries until it passes, so a
@@ -243,7 +243,7 @@ Then('the {string} {role} should be disabled', async ({ page, apiContext, env },
 // admin too — as long as the first poll lands before the fetch resolves. The hold outlives it.
 Then('the {string} {role} should stay disabled for {int} seconds', async ({ page, apiContext, env }, name, role, seconds) => {
     assertPositiveDuration(seconds);
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const locator = page.getByRole(role, { name: n });
     const deadline = Date.now() + seconds * 1000;
     do {
@@ -259,7 +259,7 @@ Then('the {string} {role} should stay disabled for {int} seconds', async ({ page
 // Known weakness, stated rather than hidden: the absent branch is satisfied by a surface that has
 // not rendered yet. Where that race is plausible, use "should stay absent for {int} seconds".
 Then('the {string} {role} should be absent or disabled', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const locator = page.getByRole(role, { name: n });
     if ((await locator.count()) === 0)
         return;
@@ -267,24 +267,24 @@ Then('the {string} {role} should be absent or disabled', async ({ page, apiConte
 });
 // Proves an element addressed by test id is actionable.
 Then('the element with test id {string} should be enabled', async ({ page, heal, apiContext, env }, id) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     const locator = await heal.resolve(page.getByTestId(testId), { testId, description: `test id "${testId}"` }, 'assert');
     await expect(locator).toBeEnabled();
 });
 // Proves an element addressed by test id is rendered but inert. Not healed — deny direction.
 Then('the element with test id {string} should be disabled', async ({ page, apiContext, env }, id) => {
-    await expect(page.getByTestId(render(id, ...scopesOf(apiContext, env)))).toBeDisabled();
+    await expect(page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env)))).toBeDisabled();
 });
 // Proves a test-id-addressed action is not actionable, in whichever shape the denial took.
 Then('the element with test id {string} should be absent or disabled', async ({ page, apiContext, env }, id) => {
-    const locator = page.getByTestId(render(id, ...scopesOf(apiContext, env)));
+    const locator = page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env)));
     if ((await locator.count()) === 0)
         return;
     await expect(locator.first()).toBeDisabled();
 });
 // Proves an opt-in is on.
 Then('the {string} checkbox should be checked', async ({ page, heal, apiContext, env }, label) => {
-    const l = render(label, ...scopesOf(apiContext, env));
+    const l = renderStrict(label, ...scopesOf(apiContext, env));
     const locator = await heal.resolve(page.getByLabel(l), { label: l, role: 'checkbox', name: l, description: `${l} checkbox` }, 'assert');
     await expect(locator).toBeChecked();
 });
@@ -294,7 +294,7 @@ Then('the {string} checkbox should be checked', async ({ page, heal, apiContext,
 // extra safety; what it buys is the failure MESSAGE — "no such checkbox is rendered" rather than a
 // retry timeout that reads as though the assertion itself were wrong.
 Then('the {string} checkbox should not be checked', async ({ page, apiContext, env }, label) => {
-    const l = render(label, ...scopesOf(apiContext, env));
+    const l = renderStrict(label, ...scopesOf(apiContext, env));
     const locator = page.getByLabel(l);
     await expect(locator, `no "${l}" checkbox is rendered`).toHaveCount(1);
     await expect(locator).not.toBeChecked();
@@ -307,7 +307,7 @@ Then('the {string} checkbox should not be checked', async ({ page, apiContext, e
 // Proves the first of several identical elements is clickable, on a surface where the built-in
 // step can only report ambiguity.
 When('I click the first element with test id {string}', async ({ page, apiContext, env }, id) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     const locator = page.getByTestId(testId);
     await expectAtLeast(locator, 1, `elements with test id "${testId}"`);
     await locator.first().click();
@@ -315,7 +315,7 @@ When('I click the first element with test id {string}', async ({ page, apiContex
 // Proves a specific row of a repeated list is reachable — the assertion a list scenario needs
 // before it can act on row 2 at all.
 When('I click the element with test id {string} at position {int}', async ({ page, apiContext, env }, id, position) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     const index = indexOfPosition(position, `elements with test id "${testId}"`);
     const locator = page.getByTestId(testId);
     await expectAtLeast(locator, position, `elements with test id "${testId}"`);
@@ -323,14 +323,14 @@ When('I click the element with test id {string} at position {int}', async ({ pag
 });
 // Proves the first of several same-named controls is clickable.
 When('I click the first {string} {role}', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const locator = page.getByRole(role, { name: n });
     await expectAtLeast(locator, 1, `"${n}" ${role} elements`);
     await locator.first().click();
 });
 // Proves a specific one of several same-named controls is clickable.
 When('I click the {string} {role} at position {int}', async ({ page, apiContext, env }, name, role, position) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const index = indexOfPosition(position, `"${n}" ${role} elements`);
     const locator = page.getByRole(role, { name: n });
     await expectAtLeast(locator, position, `"${n}" ${role} elements`);
@@ -339,28 +339,28 @@ When('I click the {string} {role} at position {int}', async ({ page, apiContext,
 // Proves the first of several identical fields accepts input.
 When('I fill the first element with test id {string} with {string}', async ({ page, apiContext, env }, id, value) => {
     const scopes = scopesOf(apiContext, env);
-    const testId = render(id, ...scopes);
+    const testId = renderStrict(id, ...scopes);
     const locator = page.getByTestId(testId);
     await expectAtLeast(locator, 1, `elements with test id "${testId}"`);
-    await locator.first().fill(render(value, ...scopes));
+    await locator.first().fill(renderStrict(value, ...scopes));
 });
 // Proves a specific row's field accepts input — editing row 3 of a repeated editor.
 When('I fill the element with test id {string} at position {int} with {string}', async ({ page, apiContext, env }, id, position, value) => {
     const scopes = scopesOf(apiContext, env);
-    const testId = render(id, ...scopes);
+    const testId = renderStrict(id, ...scopes);
     const index = indexOfPosition(position, `elements with test id "${testId}"`);
     const locator = page.getByTestId(testId);
     await expectAtLeast(locator, position, `elements with test id "${testId}"`);
-    await locator.nth(index).fill(render(value, ...scopes));
+    await locator.nth(index).fill(renderStrict(value, ...scopes));
 });
 // Proves at least one such element rendered, where the built-in visibility step would report a
 // strict-mode violation instead of an answer.
 Then('the first element with test id {string} should be visible', async ({ page, apiContext, env }, id) => {
-    await expect(page.getByTestId(render(id, ...scopesOf(apiContext, env))).first()).toBeVisible();
+    await expect(page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env))).first()).toBeVisible();
 });
 // Proves the Nth repeat rendered — i.e. that the list is at least N long AND that entry is shown.
 Then('the element with test id {string} at position {int} should be visible', async ({ page, apiContext, env }, id, position) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     const index = indexOfPosition(position, `elements with test id "${testId}"`);
     await expect(page.getByTestId(testId).nth(index), `no element with test id "${testId}" at position ${position}`).toBeVisible();
 });
@@ -368,18 +368,18 @@ Then('the element with test id {string} at position {int} should be visible', as
 // ordering or pagination scenario mean something.
 Then('the element with test id {string} at position {int} should contain {string}', async ({ page, apiContext, env }, id, position, text) => {
     const scopes = scopesOf(apiContext, env);
-    const testId = render(id, ...scopes);
+    const testId = renderStrict(id, ...scopes);
     const index = indexOfPosition(position, `elements with test id "${testId}"`);
-    await expect(page.getByTestId(testId).nth(index), `element with test id "${testId}" at position ${position}`).toContainText(render(text, ...scopes));
+    await expect(page.getByTestId(testId).nth(index), `element with test id "${testId}" at position ${position}`).toContainText(renderStrict(text, ...scopes));
 });
 // Proves at least one same-named control rendered and is shown.
 Then('the first {string} {role} should be visible', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.getByRole(role, { name: n }).first()).toBeVisible();
 });
 // Proves the Nth same-named control rendered and is shown.
 Then('the {string} {role} at position {int} should be visible', async ({ page, apiContext, env }, name, role, position) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const index = indexOfPosition(position, `"${n}" ${role} elements`);
     await expect(page.getByRole(role, { name: n }).nth(index), `no "${n}" ${role} at position ${position}`).toBeVisible();
 });
@@ -387,24 +387,24 @@ Then('the {string} {role} at position {int} should be visible', async ({ page, a
 // Proves the collection is exactly this size — the assertion that catches a duplicated render or
 // a leaked row that a "should be visible" check happily ignores.
 Then('the element with test id {string} should have exactly {int} matches', async ({ page, apiContext, env }, id, count) => {
-    await expect(page.getByTestId(render(id, ...scopesOf(apiContext, env)))).toHaveCount(count);
+    await expect(page.getByTestId(renderStrict(id, ...scopesOf(apiContext, env)))).toHaveCount(count);
 });
 // Proves the collection reached a floor, for lists whose exact length is not the point. A floor of
 // 0 is refused: it would pass on a blank page, which is not an assertion.
 Then('the element with test id {string} should have at least {int} matches', async ({ page, apiContext, env }, id, count) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     assertMeaningfulFloor(count, `elements with test id "${testId}"`);
     await expectAtLeast(page.getByTestId(testId), count, `elements with test id "${testId}"`);
 });
 // Proves exactly N same-named controls rendered — e.g. that a "Delete" appears on every row and
 // nowhere else.
 Then('there should be exactly {int} {string} {role} elements', async ({ page, apiContext, env }, count, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.getByRole(role, { name: n })).toHaveCount(count);
 });
 // Proves at least N same-named controls rendered. A floor of 0 is refused for the same reason.
 Then('there should be at least {int} {string} {role} elements', async ({ page, apiContext, env }, count, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     assertMeaningfulFloor(count, `"${n}" ${role} elements`);
     await expectAtLeast(page.getByRole(role, { name: n }), count, `"${n}" ${role} elements`);
 });
@@ -416,7 +416,7 @@ Then('there should be at least {int} {string} {role} elements', async ({ page, a
 // dialog contract. The body-focus guard is essential: `document.activeElement` falls back to
 // `<body>`, whose text is the whole page, so an unguarded name match passes for almost any string.
 Then('the focused element should be named {string}', async ({ page, apiContext, env }, name) => {
-    const wanted = render(name, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(name, ...scopesOf(apiContext, env));
     const info = await readFocus(page);
     expect(info.focused, `nothing is focused — <${info.tag}> holds focus, so no element is named "${wanted}"`).toBe(true);
     expect(info.name.toLowerCase(), `focus is on <${info.tag}> named "${info.name}", not on "${wanted}"`).toContain(wanted.toLowerCase());
@@ -439,7 +439,7 @@ Then('the focused element should be inside the open dialog', async ({ page }) =>
 // Proves focus is on one specific named control, resolved the same way a user's screen reader
 // would name it.
 Then('focus should be on the {string} {role}', async ({ page, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     await expect(page.locator(':focus'), 'nothing on the page is focused').toHaveCount(1);
     await expect(page.getByRole(role, { name: n }).first()).toBeFocused();
 });
@@ -450,7 +450,7 @@ When('I replace the focused field with {string}', async ({ page, apiContext, env
     const focused = page.locator('input:focus, textarea:focus, [contenteditable="true"]:focus');
     await expect(focused, 'no editable element is focused — did the rename affordance open?').toHaveCount(1);
     await page.keyboard.press('ControlOrMeta+a');
-    await page.keyboard.type(render(value, ...scopesOf(apiContext, env)));
+    await page.keyboard.type(renderStrict(value, ...scopesOf(apiContext, env)));
 });
 /* ── keyboard ─────────────────────────────────────────────────────────── */
 // Proves a repeated key press is expressible at all — walking a tab ring or a listbox needs it,
@@ -461,7 +461,7 @@ When('I press {string} {int} times', async ({ page, apiContext, env }, key, time
             hint: 'Press counts are whole numbers, 1 or more. A 0-press step does nothing, and any assertion that follows it would be about an untouched page.',
         });
     }
-    const k = render(key, ...scopesOf(apiContext, env));
+    const k = renderStrict(key, ...scopesOf(apiContext, env));
     for (let i = 0; i < times; i += 1)
         await page.keyboard.press(k);
 });
@@ -473,7 +473,7 @@ When('I press {string} {int} times recording every focused element', async ({ pa
             hint: 'A focus walk of 0 presses records nothing, and "every recorded focus stayed inside" would then be true of an empty list.',
         });
     }
-    const k = render(key, ...scopesOf(apiContext, env));
+    const k = renderStrict(key, ...scopesOf(apiContext, env));
     const walk = [];
     for (let i = 0; i < times; i += 1) {
         await page.keyboard.press(k);
@@ -503,13 +503,13 @@ Then('every recorded focus should have stayed inside the dialog', async ({ apiCo
 // the loop checks before it presses, because blurring first can dismiss the very overlay under
 // test.
 When('I tab to the first focusable element inside the {string} {role}', async ({ page, heal, apiContext, env }, name, role) => {
-    const n = render(name, ...scopesOf(apiContext, env));
+    const n = renderStrict(name, ...scopesOf(apiContext, env));
     const region = await heal.resolve(page.getByRole(role, { name: n }), { role: role, name: n, text: n, description: `${role} "${n}"` }, 'assert');
     await tabToFirstFocusable(page, region.first(), `the "${n}" ${role}`);
 });
 // Proves the same for a region that carries a test id rather than an accessible name.
 When('I tab to the first focusable element inside the element with test id {string}', async ({ page, heal, apiContext, env }, id) => {
-    const testId = render(id, ...scopesOf(apiContext, env));
+    const testId = renderStrict(id, ...scopesOf(apiContext, env));
     const region = await heal.resolve(page.getByTestId(testId), { testId, description: `test id "${testId}"` }, 'assert');
     await tabToFirstFocusable(page, region.first(), `the element with test id "${testId}"`);
 });
@@ -543,29 +543,29 @@ Then('no dialog should be open', async ({ page }) => {
 });
 // Proves the dialog's single unlabelled field accepts input.
 When('I fill the open dialog field with {string}', async ({ page, apiContext, env }, value) => {
-    await fillOverlayField(page.getByRole('dialog').last(), 'dialog', render(value, ...scopesOf(apiContext, env)));
+    await fillOverlayField(page.getByRole('dialog').last(), 'dialog', renderStrict(value, ...scopesOf(apiContext, env)));
 });
 // Proves the same for an alert dialog. Kept separate from `dialog` because a confirm prompt is
 // routinely stacked ON TOP of an already-open dialog, and only the role tells them apart.
 When('I fill the open alert dialog field with {string}', async ({ page, apiContext, env }, value) => {
-    await fillOverlayField(page.getByRole('alertdialog').last(), 'alert dialog', render(value, ...scopesOf(apiContext, env)));
+    await fillOverlayField(page.getByRole('alertdialog').last(), 'alert dialog', renderStrict(value, ...scopesOf(apiContext, env)));
 });
 // Proves an unlabelled popover editor accepts input — a loop-count or filter popper typically
 // holds one bare <input> with no label, id or test id.
 When('I fill the open popover field with {string}', async ({ page, apiContext, env }, value) => {
-    await fillOverlayField(page.locator(POPOVER_SELECTOR).last(), 'popover', render(value, ...scopesOf(apiContext, env)));
+    await fillOverlayField(page.locator(POPOVER_SELECTOR).last(), 'popover', renderStrict(value, ...scopesOf(apiContext, env)));
 });
 // Proves a NAMED field inside the open dialog accepts input. Needed even though the field has a
 // label: the form behind the overlay usually carries the same label, which makes an unscoped
 // `getByLabel` ambiguous rather than wrong.
 When('I fill the {string} field of the open dialog with {string}', async ({ page, apiContext, env }, label, value) => {
     const scopes = scopesOf(apiContext, env);
-    const l = render(label, ...scopes);
+    const l = renderStrict(label, ...scopes);
     const dialog = page.getByRole('dialog').last();
     await expect(dialog, 'no dialog is open').toBeVisible();
     const field = dialog.getByLabel(l);
     await expect(field, `the open dialog has no "${l}" field`).toHaveCount(1);
-    await field.fill(render(value, ...scopes));
+    await field.fill(renderStrict(value, ...scopes));
 });
 /**
  * The topmost overlay of a kind is the LAST in DOM order — portals append to <body>, so a confirm

package/dist/steps/hybrid.steps.js

@@ -2,17 +2,21 @@ import { expect } from '@playwright/test';
 import './params.js';
 import { Then, When } from '../fixtures/test.js';
 import { getPath } from '../api/json-path.js';
-import { render, renderJson } from '../api/template.js';
+import { renderJson, renderStrict } from '../api/template.js';
 /* Hybrid glue: seed through the API, verify in the browser. */
 When('I seed via {method} {string} with body:', async ({ api, apiContext, env }, method, path, body) => {
     const scopes = [apiContext.vars.toObject(), env.vars];
-    await api.send(method, render(path, ...scopes), { body: renderJson(body, ...scopes) });
+    await api.send(method, renderStrict(path, ...scopes), { body: renderJson(body, ...scopes) });
 });
-Then('the UI should show the text from JSON path {string}', async ({ page, apiContext }, jsonPath) => {
-    const value = getPath(apiContext.last().response.body, jsonPath);
+Then('the UI should show the text from JSON path {string}', async ({ page, apiContext, env }, jsonPath) => {
+    const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
+    const value = getPath(apiContext.last().response.body, path);
     await expect(page.getByText(String(value), { exact: false }).first()).toBeVisible();
 });
-When('I replay HAR {string} for {string}', async ({ page, config }, har, urlGlob) => {
+When('I replay HAR {string} for {string}', async ({ page, config, apiContext, env }, harName, glob) => {
+    const scopes = [apiContext.vars.toObject(), env.vars];
+    const har = renderStrict(harName, ...scopes);
+    const urlGlob = renderStrict(glob, ...scopes);
     const { resolve, isAbsolute } = await import('node:path');
     const file = isAbsolute(har)
         ? har