@sdods/core 0.7.2 → 0.8.0

package/dist/steps/email.steps.js

@@ -0,0 +1,182 @@
+import { expect } from '@playwright/test';
+import './params.js';
+import { BeforeScenario, Then, When } from '../fixtures/test.js';
+import { renderStrict } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+import { createMailInbox } from '../mail/index.js';
+import { extractLinks, findCode, findLinkMatching, findLinkNamed, readableText, } from '../mail/extract.js';
+// Keyed by the per-scenario ApiContext, so state never outlives or crosses a scenario.
+const states = new WeakMap();
+function stateFor(apiContext) {
+    let s = states.get(apiContext);
+    if (!s) {
+        s = { since: Date.now(), cleared: new Map(), pinned: new Map() };
+        states.set(apiContext, s);
+    }
+    return s;
+}
+/**
+ * Opens the window when the scenario starts rather than at the first email step: in the typical
+ * flow the application sends the message during a UI step, before any email step has run.
+ */
+BeforeScenario({ name: 'sdods:mail:window' }, async ({ apiContext }) => {
+    stateFor(apiContext);
+});
+function requireMail(env) {
+    if (!env.mail) {
+        throw new SdodsError('MAIL_REQUIRED', 'This scenario reads email but no mail catcher is configured.', {
+            hint: 'Declare `mail: { provider: mailpit, url: http://localhost:8025 }` in the environment yaml, and point the application under test at the same Mailpit for SMTP (port 1025 by default).',
+            docsPath: '/docs/reference/env-yaml',
+        });
+    }
+    return {
+        provider: env.mail.provider ?? 'mailpit',
+        url: env.mail.url,
+        auth: env.mail.auth,
+        pollIntervalMs: env.mail.pollIntervalMs ?? 1000,
+        clockSkewMs: env.mail.clockSkewMs ?? 2000,
+        timeoutSeconds: env.mail.timeoutSeconds ?? 15,
+    };
+}
+const scopesOf = ({ apiContext, env }) => [apiContext.vars.toObject(), env.vars];
+const arg = (fx, value) => renderStrict(value, ...scopesOf(fx));
+const addressArg = (fx, value) => arg(fx, value).trim().toLowerCase();
+function windowStart(fx, config, address) {
+    const s = stateFor(fx.apiContext);
+    return new Date(Math.max(s.since, s.cleared.get(address) ?? 0) - config.clockSkewMs);
+}
+/** Search until something matches or the deadline passes; `[]` on timeout. */
+async function pollSearch(inbox, query, timeoutMs, intervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await inbox.search(query);
+        if (found.length > 0)
+            return found;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return [];
+        await new Promise((r) => setTimeout(r, Math.min(intervalMs, left)));
+    }
+}
+function describeSeen(seen) {
+    if (seen.length === 0)
+        return 'No email at all reached that address in this scenario.';
+    const list = seen
+        .slice(0, 10)
+        .map((m) => `  - "${m.subject}" from ${m.from.address} at ${m.receivedAt.toISOString()}`)
+        .join('\n');
+    return `Emails that did reach it in this scenario (newest first):\n${list}`;
+}
+/** The message "the latest email to <address>" refers to. See the header for the rules. */
+async function latestEmail(fx, rawAddress) {
+    const config = requireMail(fx.env);
+    const inbox = createMailInbox(config);
+    const address = addressArg(fx, rawAddress);
+    const pinned = stateFor(fx.apiContext).pinned.get(address);
+    if (pinned)
+        return inbox.get(pinned);
+    const since = windowStart(fx, config, address);
+    const found = await pollSearch(inbox, { to: address, since }, config.timeoutSeconds * 1000, config.pollIntervalMs);
+    if (found.length === 0) {
+        throw new SdodsError('MAIL_NOT_RECEIVED', `No email to ${address} arrived within ${config.timeoutSeconds} s.`, {
+            hint: 'Only mail received after the scenario started (or after `I clear the inbox for` that address) counts. Check that the application sends SMTP to the Mailpit in `mail.url`, or wait explicitly with `the inbox for … should receive an email with subject containing … within … seconds`.',
+            details: { address, since: since.toISOString(), mailpit: config.url },
+        });
+    }
+    return inbox.get(found[0].id);
+}
+When('I clear the inbox for {string}', async ({ apiContext, env }, rawAddress) => {
+    const fx = { apiContext, env };
+    const config = requireMail(env);
+    const address = addressArg(fx, rawAddress);
+    await createMailInbox(config).clear(address);
+    const s = stateFor(apiContext);
+    s.cleared.set(address, Date.now());
+    s.pinned.delete(address);
+});
+Then('the inbox for {string} should receive an email with subject containing {string} within {int} seconds', async ({ apiContext, env }, rawAddress, rawSubject, seconds) => {
+    const fx = { apiContext, env };
+    const config = requireMail(env);
+    const inbox = createMailInbox(config);
+    const address = addressArg(fx, rawAddress);
+    const subject = arg(fx, rawSubject);
+    const since = windowStart(fx, config, address);
+    const found = await pollSearch(inbox, { to: address, subjectContains: subject, since }, seconds * 1000, config.pollIntervalMs);
+    if (found.length === 0) {
+        // "Nothing arrived" and "something with the wrong subject arrived" are different bugs, so
+        // the failure says which one this is.
+        const seen = await inbox.search({ to: address, since });
+        throw new SdodsError('MAIL_NOT_RECEIVED', `No email to ${address} with subject containing "${subject}" arrived within ${seconds} s.\n${describeSeen(seen)}`, {
+            hint: 'The subject match is a case-sensitive substring. Only mail received after the scenario started (or after `I clear the inbox for` that address) counts; check that the application sends SMTP to the Mailpit in `mail.url`.',
+            details: {
+                address,
+                subject,
+                since: since.toISOString(),
+                seen: seen.map((m) => ({
+                    subject: m.subject,
+                    from: m.from.address,
+                    receivedAt: m.receivedAt.toISOString(),
+                })),
+            },
+        });
+    }
+    stateFor(apiContext).pinned.set(address, found[0].id);
+});
+Then('the latest email to {string} should contain the text {string}', async ({ apiContext, env }, rawAddress, rawText) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const needle = arg(fx, rawText);
+    expect(readableText(message), `the latest email to ${message.to.map((t) => t.address).join(', ')} ("${message.subject}")`).toContain(needle);
+});
+Then('the latest email to {string} should have been sent from {string}', async ({ apiContext, env }, rawAddress, rawFrom) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const wanted = arg(fx, rawFrom).trim();
+    const { name, address } = message.from;
+    const candidates = [address, name, `${name} <${address}>`].map((s) => s.toLowerCase());
+    if (!candidates.includes(wanted.toLowerCase())) {
+        expect(name ? `${name} <${address}>` : address, `sender of "${message.subject}" (compare the address, the display name, or "Name <address>")`).toBe(wanted);
+    }
+});
+When('I save the link matching {string} from the latest email to {string} as {string}', async ({ apiContext, env }, rawPattern, rawAddress, name) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const pattern = arg(fx, rawPattern);
+    const link = findLinkMatching(message, pattern);
+    if (!link)
+        throw noLink(message, `matching ${pattern}`);
+    // `name` is the variable being written, an identifier rather than a template.
+    apiContext.vars.set(name, link.href);
+});
+When('I save the code matching {string} from the latest email to {string} as {string}', async ({ apiContext, env }, rawPattern, rawAddress, name) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const pattern = arg(fx, rawPattern);
+    const code = findCode(message, pattern);
+    if (code === undefined) {
+        throw new SdodsError('RUN_FAILED', `Nothing in "${message.subject}" matches ${pattern}.`, {
+            hint: 'The pattern is a regular expression over the text part (or the HTML part rendered to text). With a capture group, group 1 is saved: `code: (\\d{6})`.',
+            details: { subject: message.subject, text: readableText(message).slice(0, 1000) },
+        });
+    }
+    apiContext.vars.set(name, code);
+});
+When('I open the link {string} from the latest email to {string}', async ({ apiContext, env, page }, rawName, rawAddress) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const name = arg(fx, rawName);
+    const link = findLinkNamed(message, name);
+    if (!link)
+        throw noLink(message, `named "${name}"`);
+    await page.goto(link.href, { waitUntil: 'domcontentloaded' });
+});
+function noLink(message, what) {
+    const links = extractLinks(message);
+    return new SdodsError('RUN_FAILED', `No link ${what} in "${message.subject}".`, {
+        hint: links.length
+            ? `Links in that email:\n${links.map((l) => `  - ${l.text ? `"${l.text}" ` : ''}${l.href}`).join('\n')}`
+            : 'That email has no links at all: no <a href> in the HTML part and no http(s) URL in the text part.',
+        details: { subject: message.subject, links },
+    });
+}
+//# sourceMappingURL=email.steps.js.map

package/dist/steps/hybrid.steps.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Then, When } from '../fixtures/test.js';
-import { getPath } from '../api/json-path.js';
+import { matchedPath } from '../api/json-path.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) => {
@@ -10,7 +10,7 @@ When('I seed via {method} {string} with body:', async ({ api, apiContext, env },
 });
 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);
+    const value = matchedPath(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, apiContext, env }, harName, glob) => {

package/dist/steps/index.d.ts

@@ -17,6 +17,8 @@ import './browser.steps.js';
 import './dom.steps.js';
 import './net.steps.js';
 import './perf.steps.js';
+import './email.steps.js';
+import './canvas.steps.js';
 import '../shots/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/steps/index.js

@@ -17,6 +17,8 @@ import './browser.steps.js';
 import './dom.steps.js';
 import './net.steps.js';
 import './perf.steps.js';
+import './email.steps.js';
+import './canvas.steps.js';
 import '../shots/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/core",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "SDODS runtime: configuration, project registry, fixtures, step libraries, data providers, screenshot narratives and self-healing locators.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -21,6 +21,7 @@
     "./analyze": "./dist/analyze/index.js",
     "./recorder": "./dist/recorder/index.js",
     "./har": "./dist/har/index.js",
+    "./load": "./dist/load/index.js",
     "./auth": "./dist/auth/index.js",
     "./insights": "./dist/insights/index.js",
     "./reporters/dashboard": "./dist/reporters/dashboard.js",
@@ -42,7 +43,7 @@
     "playwright-bdd": ">=9"
   },
   "dependencies": {
-    "@sdods/contracts": "0.7.2",
+    "@sdods/contracts": "0.8.0",
     "@cucumber/cucumber-expressions": "19.0.0",
     "@cucumber/gherkin": "^42.0.1",
     "@cucumber/messages": "^34.2.1",
@@ -60,7 +61,7 @@
     "tsx": "^4.23.0",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@sdods/db": "0.7.2"
+    "@sdods/db": "0.8.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {