@sdods/core 0.3.2 → 0.5.2

package/dist/steps/api.steps.js

@@ -2,30 +2,41 @@ import { expect } from '@playwright/test';
 import './params.js';
 import { Given, Then, When } from '../fixtures/test.js';
 import { coerce, getPath } from '../api/json-path.js';
-import { render, renderJson } from '../api/template.js';
+import { renderJson, renderStrict } from '../api/template.js';
 import { pollUntil } from '../api/poll.js';
 import { loadJsonSchema, loadZodSchema, validateAgainstOpenApi, validateJsonSchema, validateZod, } from '../api/validate.js';
 import { SdodsError } from '../errors.js';
 /* ── requests ─────────────────────────────────────────────────────────── */
 When('I send a {method} request to {string}', async ({ api, apiContext, env }, method, path) => {
-    await api.send(method, render(path, apiContext.vars.toObject(), env.vars));
+    await api.send(method, renderStrict(path, apiContext.vars.toObject(), env.vars));
 });
 When('I send a {method} request to {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) });
+});
+/**
+ * The doc string goes out byte-for-byte: not parsed, not re-serialised, and not template-rendered
+ * (only the path is). This is how a malformed-input scenario sends `{ this is not json`; the
+ * `with body:` step parses a `json` doc string and would throw before sending.
+ * The content-type defaults to `application/json`; set another with `I set the request header`.
+ */
+When('I send a {method} request to {string} with the raw body:', async ({ api, apiContext, env }, method, path, body) => {
+    await api.send(method, renderStrict(path, apiContext.vars.toObject(), env.vars), {
+        body: Buffer.from(body, 'utf8'),
+    });
 });
 When('I send a {method} request to {string} with form:', async ({ api, apiContext, env }, method, path, table) => {
     const scopes = [apiContext.vars.toObject(), env.vars];
     const form = {};
     for (const [k, v] of table.raw())
-        form[k] = render(String(v ?? ''), ...scopes);
-    await api.send(method, render(path, ...scopes), { form });
+        form[k] = renderStrict(String(v ?? ''), ...scopes);
+    await api.send(method, renderStrict(path, ...scopes), { form });
 });
 Given('I set the request header {string} to {string}', async ({ apiContext, env }, name, value) => {
-    apiContext.headers.set(name, render(value, apiContext.vars.toObject(), env.vars));
+    apiContext.headers.set(name, renderStrict(value, apiContext.vars.toObject(), env.vars));
 });
 Given('I set the query parameter {string} to {string}', async ({ apiContext, env }, name, value) => {
-    apiContext.query.set(name, render(value, apiContext.vars.toObject(), env.vars));
+    apiContext.query.set(name, renderStrict(value, apiContext.vars.toObject(), env.vars));
 });
 Given('I clear the request headers and query parameters', async ({ apiContext }) => {
     apiContext.resetRequestState();
@@ -40,8 +51,8 @@ Given('I authenticate with basic credentials {string} and {string}', async ({ ap
     const scopes = [apiContext.vars.toObject(), env.vars];
     apiContext.auth = {
         type: 'basic',
-        username: render(username, ...scopes),
-        password: render(password, ...scopes),
+        username: renderStrict(username, ...scopes),
+        password: renderStrict(password, ...scopes),
     };
 });
 Given('I use no authentication', async ({ apiContext }) => {
@@ -51,6 +62,14 @@ Given('I use no authentication', async ({ apiContext }) => {
     // refusal matters.
     apiContext.auth = null;
 });
+/**
+ * Send the rest of the scenario's API calls through a request context with an empty cookie jar,
+ * so they carry only the credentials the scenario set. Without it, @ui/@hybrid calls also carry the
+ * leased role's session cookie, and "credential X alone is refused" can pass on the session.
+ */
+Given('I use an isolated API client', async ({ apiContext }) => {
+    apiContext.isolated = true;
+});
 /* ── assertions ───────────────────────────────────────────────────────── */
 Then('the response status should be {int}', async ({ apiContext }, status) => {
     expect(apiContext.last().response.status, `expected HTTP ${status}, got ${apiContext.last().response.status} ${apiContext.last().response.statusText}`).toBe(status);
@@ -65,70 +84,88 @@ Then('the response status should be one of {string}', async ({ apiContext }, lis
 Then('the response should contain {string}', async ({ apiContext, env }, text) => {
     const body = apiContext.last().response.body;
     const haystack = typeof body === 'string' ? body : JSON.stringify(body);
-    expect(haystack).toContain(render(text, apiContext.vars.toObject(), env.vars));
+    expect(haystack).toContain(renderStrict(text, apiContext.vars.toObject(), env.vars));
 });
-Then('the response JSON path {string} should equal {string}', async ({ apiContext, env }, path, expected) => {
+Then('the response JSON path {string} should equal {string}', async ({ apiContext, env }, jsonPath, expected) => {
+    const scopes = [apiContext.vars.toObject(), env.vars];
+    const path = renderStrict(jsonPath, ...scopes);
     const actual = getPath(apiContext.last().response.body, path);
-    expect(actual, `JSON path ${path}`).toEqual(coerce(render(expected, apiContext.vars.toObject(), env.vars)));
+    expect(actual, `JSON path ${path}`).toEqual(coerce(renderStrict(expected, ...scopes)));
 });
-Then('the response JSON path {string} should exist', async ({ apiContext }, path) => {
+Then('the response JSON path {string} should exist', async ({ apiContext, env }, jsonPath) => {
+    const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
     expect(getPath(apiContext.last().response.body, path), `JSON path ${path}`).toBeDefined();
 });
-Then('the response JSON path {string} should match {string}', async ({ apiContext }, path, pattern) => {
+Then('the response JSON path {string} should match {string}', async ({ apiContext, env }, jsonPath, pattern) => {
+    const scopes = [apiContext.vars.toObject(), env.vars];
+    const path = renderStrict(jsonPath, ...scopes);
     const actual = getPath(apiContext.last().response.body, path);
-    expect(String(actual), `JSON path ${path}`).toMatch(new RegExp(pattern));
+    expect(String(actual), `JSON path ${path}`).toMatch(new RegExp(renderStrict(pattern, ...scopes)));
 });
-Then('the response JSON path {string} should have {int} items', async ({ apiContext }, path, count) => {
+Then('the response JSON path {string} should have {int} items', async ({ apiContext, env }, jsonPath, count) => {
+    const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
     const actual = getPath(apiContext.last().response.body, path);
     expect(Array.isArray(actual) ? actual.length : -1, `JSON path ${path} length`).toBe(count);
 });
-Then('the response JSON path {string} should have at least {int} items', async ({ apiContext }, path, count) => {
+Then('the response JSON path {string} should have at least {int} items', async ({ apiContext, env }, jsonPath, count) => {
+    const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
     const actual = getPath(apiContext.last().response.body, path);
     expect(Array.isArray(actual) ? actual.length : -1, `JSON path ${path} length`).toBeGreaterThanOrEqual(count);
 });
 Then('the response body should be an array', async ({ apiContext }) => {
     expect(Array.isArray(apiContext.last().response.body)).toBe(true);
 });
-Then('the response header {string} should contain {string}', async ({ apiContext }, name, value) => {
-    expect(apiContext.last().response.headers[name.toLowerCase()] ?? '').toContain(value);
+Then('the response header {string} should contain {string}', async ({ apiContext, env }, name, value) => {
+    const scopes = [apiContext.vars.toObject(), env.vars];
+    const header = renderStrict(name, ...scopes).toLowerCase();
+    expect(apiContext.last().response.headers[header] ?? '').toContain(renderStrict(value, ...scopes));
 });
 Then('the response time should be under {int} ms', async ({ apiContext }, maxMs) => {
     expect(apiContext.last().response.responseTime).toBeLessThan(maxMs);
 });
-Then('the response should match the JSON schema {string}', async ({ apiContext, config }, file) => {
+Then('the response should match the JSON schema {string}', async ({ apiContext, config, env }, schemaFile) => {
+    const file = renderStrict(schemaFile, apiContext.vars.toObject(), env.vars);
     const result = validateJsonSchema(apiContext.last().response.body, loadJsonSchema(config, file));
     expect(result.ok, `schema ${file} violations:\n${result.errors.join('\n')}`).toBe(true);
 });
-Then('the response should match the zod schema {string}', async ({ apiContext, config }, spec) => {
+Then('the response should match the zod schema {string}', async ({ apiContext, config, env }, zodSpec) => {
+    const spec = renderStrict(zodSpec, apiContext.vars.toObject(), env.vars);
     const result = validateZod(apiContext.last().response.body, await loadZodSchema(config, spec));
     expect(result.ok, `zod schema ${spec} violations:\n${result.errors.join('\n')}`).toBe(true);
 });
-Then('the response should match the OpenAPI schema for {method} {string}', async ({ apiContext, config }, method, path) => {
+Then('the response should match the OpenAPI schema for {method} {string}', async ({ apiContext, config, env }, method, openApiPath) => {
+    // Single-brace `{id}` path parameters are not placeholders, so they pass through untouched.
+    const path = renderStrict(openApiPath, apiContext.vars.toObject(), env.vars);
     const last = apiContext.last();
     const result = await validateAgainstOpenApi(config, method, path, last.response.status, last.response.body);
     expect(result.ok, `OpenAPI ${method} ${path} violations:\n${result.errors.join('\n')}`).toBe(true);
 });
 /* ── chaining & polling ───────────────────────────────────────────────── */
-When('I save the response JSON path {string} as {string}', async ({ apiContext }, path, name) => {
+When('I save the response JSON path {string} as {string}', async ({ apiContext, env }, jsonPath, name) => {
+    // `name` is the variable being written, an identifier rather than a template.
+    const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
     const value = getPath(apiContext.last().response.body, path);
     if (value === undefined)
         throw new SdodsError('RUN_FAILED', `JSON path ${path} is undefined in the last response; cannot save as {{${name}}}.`);
     apiContext.vars.set(name, value);
 });
 Given('I set the variable {string} to {string}', async ({ apiContext, env }, name, value) => {
-    apiContext.vars.set(name, coerce(render(value, apiContext.vars.toObject(), env.vars)));
+    apiContext.vars.set(name, coerce(renderStrict(value, apiContext.vars.toObject(), env.vars)));
 });
 When('I poll {method} {string} until JSON path {string} equals {string} within {int} seconds', async ({ api, apiContext, env }, method, path, jsonPath, expected, seconds) => {
     const scopes = [apiContext.vars.toObject(), env.vars];
-    const want = coerce(render(expected, ...scopes));
-    await pollUntil(() => api.send(method, render(path, ...scopes)), (snap) => JSON.stringify(getPath(snap.response.body, jsonPath)) === JSON.stringify(want), {
+    // Rendered before polling, so an unset variable fails at once rather than inside every attempt.
+    const want = coerce(renderStrict(expected, ...scopes));
+    const url = renderStrict(path, ...scopes);
+    const at = renderStrict(jsonPath, ...scopes);
+    await pollUntil(() => api.send(method, url), (snap) => JSON.stringify(getPath(snap.response.body, at)) === JSON.stringify(want), {
         timeoutMs: seconds * 1000,
         intervalMs: 1000,
         description: `${method} ${path} → ${jsonPath} == ${expected}`,
     });
 });
 When('I poll {method} {string} until the status is {int} within {int} seconds', async ({ api, apiContext, env }, method, path, status, seconds) => {
-    await pollUntil(() => api.send(method, render(path, apiContext.vars.toObject(), env.vars)), (snap) => snap.response.status === status, {
+    await pollUntil(() => api.send(method, renderStrict(path, apiContext.vars.toObject(), env.vars)), (snap) => snap.response.status === status, {
         timeoutMs: seconds * 1000,
         intervalMs: 1000,
         description: `${method} ${path} → HTTP ${status}`,

package/dist/steps/browser.steps.js

@@ -1,6 +1,6 @@
 import { expect } from '@playwright/test';
 import { Given, Then, When } from '../fixtures/test.js';
-import { render } from '../api/template.js';
+import { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 /**
  * Browser-state steps: cookies, web storage, viewport, colour scheme, locale and console.
@@ -10,7 +10,8 @@ import { SdodsError } from '../errors.js';
  * step PROVES; where a step exists because of a specific trap, the trap is named.
  *
  * Two rules govern the whole file:
- *   * every string argument is interpolated through `render()`, so `{{vars}}` work everywhere;
+ *   * every string argument is interpolated through `renderStrict()`, so `{{vars}}` work everywhere
+ *     and an unset one fails the step instead of being matched literally;
  *   * no assertion may pass over an empty set. A selector that matches nothing, a body that
  *     rendered no text, a recorder that was never armed and a page that never navigated are all
  *     failures, because a green step that observed nothing is worse than no step at all.
@@ -43,8 +44,8 @@ Given('I set the browser cookie {string} to {string}', async ({ page, apiContext
     const scopes = scopesOf(apiContext, env);
     await page.context().addCookies([
         {
-            name: render(name, ...scopes),
-            value: render(value, ...scopes),
+            name: renderStrict(name, ...scopes),
+            value: renderStrict(value, ...scopes),
             url: baseUrlOf(env, 'I set the browser cookie'),
         },
     ]);
@@ -54,7 +55,7 @@ Given('I set the browser cookie {string} to {string}', async ({ page, apiContext
 // read-filter-restore. Clearing the jar to drop a session cookie would also drop the consent and
 // locale cookies the scenario set up, and the failure would look like a bug in the app.
 Given('I clear the browser cookie {string}', async ({ page, apiContext, env }, name) => {
-    const wanted = render(name, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(name, ...scopesOf(apiContext, env));
     const context = page.context();
     const all = await context.cookies();
     const survivors = all.filter((c) => c.name !== wanted);
@@ -71,19 +72,19 @@ Given('I clear all browser cookies', async ({ page }) => {
 // `document.cookie`, so the browser context is the only place its value is observable at all.
 Then('the browser cookie {string} should equal {string}', async ({ page, apiContext, env }, name, expected) => {
     const scopes = scopesOf(apiContext, env);
-    const wanted = render(name, ...scopes);
+    const wanted = renderStrict(name, ...scopes);
     const cookie = await findCookie(page, wanted);
     expect(cookie, `cookie "${wanted}" is not in the jar`).toBeTruthy();
-    expect(cookie.value, `cookie "${wanted}"`).toBe(render(expected, ...scopes));
+    expect(cookie.value, `cookie "${wanted}"`).toBe(renderStrict(expected, ...scopes));
 });
 // Proves the cookie was issued at all, for cases where the value is opaque or random.
 Then('the browser cookie {string} should exist', async ({ page, apiContext, env }, name) => {
-    const wanted = render(name, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(name, ...scopesOf(apiContext, env));
     expect(await findCookie(page, wanted), `cookie "${wanted}" is not in the jar`).toBeTruthy();
 });
 // Proves a logout, a rejected consent or a declined attribution left nothing behind.
 Then('the browser cookie {string} should not exist', async ({ page, apiContext, env }, name) => {
-    const wanted = render(name, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(name, ...scopesOf(apiContext, env));
     expect(await findCookie(page, wanted), `unexpected cookie "${wanted}"`).toBeUndefined();
 });
 /** The attributes Playwright actually reports. Anything else is an authoring mistake. */
@@ -94,8 +95,8 @@ const COOKIE_ATTRIBUTES = ['domain', 'path', 'expires', 'httpOnly', 'secure', 's
 // string "undefined", so the step would pass while asserting nothing; the allowlist refuses it.
 Then('the browser cookie {string} should carry {string} equal to {string}', async ({ page, apiContext, env }, name, attribute, value) => {
     const scopes = scopesOf(apiContext, env);
-    const wanted = render(name, ...scopes);
-    const attr = render(attribute, ...scopes);
+    const wanted = renderStrict(name, ...scopes);
+    const attr = renderStrict(attribute, ...scopes);
     if (!COOKIE_ATTRIBUTES.includes(attr))
         throw new SdodsError('RUN_FAILED', `"${attr}" is not a cookie attribute.`, {
             hint: `Use one of: ${COOKIE_ATTRIBUTES.join(', ')}.`,
@@ -103,7 +104,7 @@ Then('the browser cookie {string} should carry {string} equal to {string}', asyn
     const cookie = await findCookie(page, wanted);
     expect(cookie, `cookie "${wanted}" is not in the jar`).toBeTruthy();
     const actual = cookie[attr];
-    expect(String(actual), `${wanted}.${attr}`).toBe(render(value, ...scopes));
+    expect(String(actual), `${wanted}.${attr}`).toBe(renderStrict(value, ...scopes));
 });
 async function findCookie(page, name) {
     return (await page.context().cookies()).find((c) => c.name === name);
@@ -172,17 +173,17 @@ async function readStorage(page, kind, key) {
 // banner — reaches it before the first paint rather than after it.
 Given('I seed local storage {string} with {string}', async ({ page, apiContext, env }, key, value) => {
     const scopes = scopesOf(apiContext, env);
-    await seedStorage(page, 'local', render(key, ...scopes), render(value, ...scopes));
+    await seedStorage(page, 'local', renderStrict(key, ...scopes), renderStrict(value, ...scopes));
 });
 // Same contract as local storage, for the per-tab values an app keeps out of the persistent store.
 Given('I seed session storage {string} with {string}', async ({ page, apiContext, env }, key, value) => {
     const scopes = scopesOf(apiContext, env);
-    await seedStorage(page, 'session', render(key, ...scopes), render(value, ...scopes));
+    await seedStorage(page, 'session', renderStrict(key, ...scopes), renderStrict(value, ...scopes));
 });
 // Proves the DEFAULT path: what the app does for a visitor with no stored preference. Removal is
 // armed as an init script as well as applied in place, so the next navigation cannot resurrect it.
 Given('I clear the local storage key {string}', async ({ page, apiContext, env }, key) => {
-    const wanted = render(key, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(key, ...scopesOf(apiContext, env));
     await page.addInitScript((k) => {
         try {
             window.localStorage.removeItem(k);
@@ -228,25 +229,25 @@ Given('I clear all browser storage', async ({ page }) => {
 // reaches storage looks identical on screen until the next page load.
 Then('local storage {string} should equal {string}', async ({ page, apiContext, env }, key, expected) => {
     const scopes = scopesOf(apiContext, env);
-    const k = render(key, ...scopes);
-    expect(await readStorage(page, 'local', k), `local storage "${k}"`).toBe(render(expected, ...scopes));
+    const k = renderStrict(key, ...scopes);
+    expect(await readStorage(page, 'local', k), `local storage "${k}"`).toBe(renderStrict(expected, ...scopes));
 });
 // Proves a sign-out, a reset or a decline actually removed the key rather than blanking the UI.
 Then('local storage {string} should be absent', async ({ page, apiContext, env }, key) => {
-    const k = render(key, ...scopesOf(apiContext, env));
+    const k = renderStrict(key, ...scopesOf(apiContext, env));
     expect(await readStorage(page, 'local', k), `local storage "${k}"`).toBeNull();
 });
 // Per-tab equivalent of the local-storage absence assertion, so a tab-scoped value that outlives
 // the flow which set it fails as loudly as a persisted one.
 Then('session storage {string} should be absent', async ({ page, apiContext, env }, key) => {
-    const k = render(key, ...scopesOf(apiContext, env));
+    const k = renderStrict(key, ...scopesOf(apiContext, env));
     expect(await readStorage(page, 'session', k), `session storage "${k}"`).toBeNull();
 });
 // Per-tab equivalent of the local-storage assertion.
 Then('session storage {string} should equal {string}', async ({ page, apiContext, env }, key, expected) => {
     const scopes = scopesOf(apiContext, env);
-    const k = render(key, ...scopes);
-    expect(await readStorage(page, 'session', k), `session storage "${k}"`).toBe(render(expected, ...scopes));
+    const k = renderStrict(key, ...scopes);
+    expect(await readStorage(page, 'session', k), `session storage "${k}"`).toBe(renderStrict(expected, ...scopes));
 });
 /* ── viewport and reflow ──────────────────────────────────────────────── */
 // Proves a layout at a width the project's fixed viewport never visits. WCAG 2.2 reflow is a
@@ -300,7 +301,7 @@ Then('the page should not scroll horizontally', async ({ page }) => {
 // to scroll internally must not push the page. Fails when the selector matches nothing, because a
 // containment claim about an element that is not on the page is not a claim.
 Then('the element matching {string} should not overflow horizontally', async ({ page, apiContext, env }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     const info = (await page.evaluate((s) => {
         const el = document.querySelector(s);
         if (!el)
@@ -316,7 +317,7 @@ const COLOUR_SCHEMES = ['light', 'dark', 'no-preference'];
 // its own preference is seeded with `Given I seed local storage …` instead, and a complete dark-mode
 // scenario usually needs both.
 Given('I emulate the {string} colour scheme', async ({ page, apiContext, env }, scheme) => {
-    const wanted = render(scheme, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(scheme, ...scopesOf(apiContext, env));
     if (!COLOUR_SCHEMES.includes(wanted))
         throw new SdodsError('RUN_FAILED', `"${wanted}" is not a colour scheme.`, {
             hint: `Use one of: ${COLOUR_SCHEMES.join(', ')}.`,
@@ -386,13 +387,13 @@ function expectLight(painted, subject) {
 // Proves the CLASS was applied. Necessary but never sufficient: a `dark` class with no CSS behind
 // it is not dark mode, which is why the painted-background steps exist alongside it.
 Then('the html element should carry the {string} class', async ({ page, apiContext, env }, cls) => {
-    const wanted = render(cls, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(cls, ...scopesOf(apiContext, env));
     const classes = await page.evaluate(() => document.documentElement.className);
     expect(String(classes).split(/\s+/).filter(Boolean), `html class list is "${classes}"`).toContain(wanted);
 });
 // Proves the theme class was REMOVED — the direction that catches a toggle which only ever adds.
 Then('the html element should not carry the {string} class', async ({ page, apiContext, env }, cls) => {
-    const wanted = render(cls, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(cls, ...scopesOf(apiContext, env));
     const classes = await page.evaluate(() => document.documentElement.className);
     expect(String(classes).split(/\s+/).filter(Boolean), `html class list is "${classes}"`).not.toContain(wanted);
 });
@@ -408,7 +409,7 @@ Then('the painted page background should be light', async ({ page }) => {
 // Proves ONE surface themed — a panel, a modal, a sidebar. Whole-page checks miss the component
 // that kept a hardcoded white while everything around it went dark.
 Then('the element matching {string} should paint a dark background', async ({ page, apiContext, env }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     expectDark(await paintedColour(page, sel, `the element matching "${sel}"`), `"${sel}"`);
 });
 /** Where the first-frame sample is parked. Stable by design: the assertion step reads it back. */
@@ -477,8 +478,8 @@ Given('I switch the interface locale to {string} using the {string} cookie', asy
     requireNavigated(page, 'I switch the interface locale');
     await page.context().addCookies([
         {
-            name: render(cookieName, ...scopes),
-            value: render(locale, ...scopes),
+            name: renderStrict(cookieName, ...scopes),
+            value: renderStrict(locale, ...scopes),
             url: baseUrlOf(env, 'I switch the interface locale'),
         },
     ]);
@@ -491,14 +492,14 @@ Given('I switch the interface locale to {string} using the {string} cookie', asy
 Given('I request the locale {string} with the Accept-Language header', async ({ page, apiContext, env }, locale) => {
     requireNavigated(page, 'I request the locale with the Accept-Language header');
     await page.setExtraHTTPHeaders({
-        'Accept-Language': render(locale, ...scopesOf(apiContext, env)),
+        'Accept-Language': renderStrict(locale, ...scopesOf(apiContext, env)),
     });
     await page.reload({ waitUntil: 'domcontentloaded' });
 });
 // Proves the document declared the language it served. Screen readers, hyphenation and every
 // `:lang()` rule key off this, and it is the one machine-checkable trace of the negotiation.
 Then('the html lang attribute should be {string}', async ({ page, apiContext, env }, lang) => {
-    const wanted = render(lang, ...scopesOf(apiContext, env));
+    const wanted = renderStrict(lang, ...scopesOf(apiContext, env));
     const actual = await page.evaluate(() => document.documentElement.getAttribute('lang'));
     expect(actual, 'html lang attribute').toBe(wanted);
 });
@@ -623,7 +624,7 @@ Then('no console error should have been recorded', async ({ apiContext }) => {
 // hydration mismatch, a blocked request — while tolerating noise the team has accepted.
 Then('no console error should match {string}', async ({ apiContext, env }, pattern) => {
     const recording = recordingFor(apiContext, 'no console error should match');
-    const rendered = render(pattern, apiContext.vars.toObject(), env.vars);
+    const rendered = renderStrict(pattern, apiContext.vars.toObject(), env.vars);
     const re = compilePattern(rendered, 'no console error should match');
     expect(recording.errors.filter((line) => re.test(line)), `console errors matching /${rendered}/`).toEqual([]);
 });
@@ -631,7 +632,7 @@ Then('no console error should match {string}', async ({ apiContext, env }, patte
 // deprecated API — never at error level.
 Then('no console warning should match {string}', async ({ apiContext, env }, pattern) => {
     const recording = recordingFor(apiContext, 'no console warning should match');
-    const rendered = render(pattern, apiContext.vars.toObject(), env.vars);
+    const rendered = renderStrict(pattern, apiContext.vars.toObject(), env.vars);
     const re = compilePattern(rendered, 'no console warning should match');
     expect(recording.warnings.filter((line) => re.test(line)), `console warnings matching /${rendered}/`).toEqual([]);
 });
@@ -640,7 +641,7 @@ Then('no console warning should match {string}', async ({ apiContext, env }, pat
 // a recorder that silently stopped working would leave every "no console error" step green.
 Then('a console error matching {string} should have been recorded', async ({ apiContext, env }, pattern) => {
     const recording = recordingFor(apiContext, 'a console error matching … should have been recorded');
-    const rendered = render(pattern, apiContext.vars.toObject(), env.vars);
+    const rendered = renderStrict(pattern, apiContext.vars.toObject(), env.vars);
     const re = compilePattern(rendered, 'a console error matching … should have been recorded');
     expect(recording.errors.filter((line) => re.test(line)).length, `no console error matched /${rendered}/. Recorded: ${recording.errors.slice(0, 10).join(' | ') || '(none)'}`).toBeGreaterThan(0);
 });

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}`,