@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/makeModuleManifestDoc.js

@@ -0,0 +1,174 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+const EXPORT_KINDS = ['pages', 'components', 'menus', 'connections', 'api'];
+
+// The build does not check every part of module.lowdefy.yaml this page reads
+// (exports above all), so a part with the wrong shape is named on the page
+// instead of failing every docs call that reads it.
+function invalidLine({ label, expected, value, depth = 0 }) {
+  return `${'  '.repeat(
+    depth
+  )}- ${label}: not valid in module.lowdefy.yaml, expected ${expected}. Received ${
+    JSON.stringify(value) ?? 'undefined'
+  }.`;
+}
+
+// A var default that is an operator, or a body the build defers, has no value
+// until the module is built for a consumer.
+function formatDefault(value) {
+  if (type.isObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.some((key) => key === '~deferred') || (keys.length === 1 && keys[0].startsWith('_'))) {
+      return 'computed';
+    }
+  }
+  return `\`${JSON.stringify(value)}\``;
+}
+
+function varLines({ varDefs, prefix, depth }) {
+  const lines = [];
+  for (const [name, definition] of Object.entries(varDefs)) {
+    const fullName = prefix ? `${prefix}.${name}` : name;
+    if (!type.isObject(definition)) {
+      lines.push(
+        invalidLine({ label: `\`${fullName}\``, expected: 'an object', value: definition, depth })
+      );
+      continue;
+    }
+    const details = [];
+    if (!type.isNone(definition.type)) {
+      details.push(definition.type);
+    }
+    if (definition.required === true) {
+      details.push('required');
+    }
+    if (!type.isUndefined(definition.default)) {
+      details.push(`default ${formatDefault(definition.default)}`);
+    }
+    const detail = details.length > 0 ? ` (${details.join(', ')})` : '';
+    const description = type.isString(definition.description) ? `: ${definition.description}` : '';
+    lines.push(`${'  '.repeat(depth)}- \`${fullName}\`${detail}${description}`);
+    if (type.isObject(definition.properties)) {
+      lines.push(
+        ...varLines({ varDefs: definition.properties, prefix: fullName, depth: depth + 1 })
+      );
+    }
+  }
+  return lines;
+}
+
+function idLines({ items, label }) {
+  if (type.isNone(items)) {
+    return [];
+  }
+  if (!type.isArray(items)) {
+    return [invalidLine({ label: `\`${label}\``, expected: 'a list', value: items })];
+  }
+  return items.map((item, index) => {
+    if (!type.isObject(item) || !type.isString(item.id)) {
+      return invalidLine({
+        label: `\`${label}.${index}\``,
+        expected: 'an object with a string id',
+        value: item,
+      });
+    }
+    const description = type.isString(item.description) ? `: ${item.description}` : '';
+    return `- \`${item.id}\`${description}`;
+  });
+}
+
+function componentLines({ manifest }) {
+  const exported = manifest.exports?.components;
+  const exportedDescriptions = new Map(
+    (type.isArray(exported) ? exported : [])
+      .filter((item) => type.isObject(item))
+      .map((item) => [item.id, item.description])
+  );
+  const components = manifest.components;
+  if (!type.isArray(components)) {
+    return idLines({ items: components, label: 'components' });
+  }
+  return idLines({
+    items: components.map((item) =>
+      type.isObject(item)
+        ? { id: item.id, description: item.description ?? exportedDescriptions.get(item.id) }
+        : item
+    ),
+    label: 'components',
+  });
+}
+
+function exportLines({ manifest }) {
+  const moduleExports = manifest.exports;
+  if (type.isNone(moduleExports)) {
+    return [];
+  }
+  if (!type.isObject(moduleExports)) {
+    return [invalidLine({ label: '`exports`', expected: 'an object', value: moduleExports }), ''];
+  }
+  const lines = [];
+  for (const kind of EXPORT_KINDS) {
+    const items = idLines({ items: moduleExports[kind], label: `exports.${kind}` });
+    if (items.length > 0) {
+      lines.push(`### ${kind}`, '', ...items, '');
+    }
+  }
+  return lines;
+}
+
+// The interface a module declares in module.lowdefy.yaml, as markdown.
+function makeModuleManifestDoc({ moduleEntry }) {
+  const manifest = type.isObject(moduleEntry.manifest) ? moduleEntry.manifest : {};
+  const lines = [`# ${moduleEntry.id} module: components, exports and vars`, ''];
+  if (type.isString(manifest.name)) {
+    lines.push(`**${manifest.name}**`, '');
+  }
+  if (type.isString(manifest.description)) {
+    lines.push(manifest.description, '');
+  }
+  lines.push(
+    `Source: \`${moduleEntry.source}\`. Module id in this app: \`${moduleEntry.id}\`.`,
+    ''
+  );
+
+  lines.push('## Vars', '');
+  const varDefs = moduleEntry.varDefs ?? {};
+  let vars;
+  if (type.isObject(varDefs)) {
+    vars = varLines({ varDefs, prefix: '', depth: 0 });
+  } else {
+    vars = [invalidLine({ label: '`vars`', expected: 'an object', value: varDefs })];
+  }
+  lines.push(...(vars.length > 0 ? vars : ['None declared.']), '');
+  lines.push(
+    `Set vars in lowdefy.yaml under \`modules\`, on the entry with \`id: ${moduleEntry.id}\`.`,
+    ''
+  );
+
+  lines.push('## Components', '');
+  const components = componentLines({ manifest });
+  lines.push(...(components.length > 0 ? components : ['None declared.']), '');
+
+  lines.push('## Exports', '');
+  const exportsSection = exportLines({ manifest });
+  lines.push(...(exportsSection.length > 0 ? exportsSection : ['None declared.', '']));
+  return lines.join('\n');
+}
+
+export default makeModuleManifestDoc;

package/lib/docs/matchExercisedPages.js

@@ -0,0 +1,35 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { matchPagePath } from '@lowdefy/node-utils';
+
+// The page ids behind the request paths a journey's browsers loaded, matched
+// through the route table the way the page route matches them, so every
+// instance of a patterned page names the one page. A path no page answers
+// names none.
+function matchExercisedPages({ routes, pagePaths }) {
+  const pageIds = new Set();
+  pagePaths.forEach((path) => {
+    const match = matchPagePath({ routes, path });
+    if (!type.isNone(match)) {
+      pageIds.add(match.pageId);
+    }
+  });
+  return [...pageIds].sort();
+}
+
+export default matchExercisedPages;

package/lib/docs/matchJourneyRoute.js

@@ -0,0 +1,69 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+function decodeSegments(text) {
+  return text
+    .split('/')
+    .filter((segment) => segment !== '')
+    .map((segment) => decodeURIComponent(segment));
+}
+
+// Names the dev server route a journey's browser request hit, from its URL
+// and method, with the app's basePath honoured. A page request carries its
+// request path, which collectExercised matches to a page id through the route
+// table. Requests to other origins and to every other route are null.
+function matchJourneyRoute({ url, method, origin, basePath = '' }) {
+  const parsed = new URL(url);
+  if (parsed.origin !== origin) {
+    return null;
+  }
+  const prefix = `${basePath}/api/`;
+  if (!parsed.pathname.startsWith(prefix)) {
+    return null;
+  }
+  const rest = parsed.pathname.slice(prefix.length);
+  if (rest === 'root' && method === 'GET') {
+    return { route: 'root' };
+  }
+  if (rest.startsWith('page/') && method === 'GET') {
+    const path = rest.slice('page/'.length);
+    if (path === '') {
+      return null;
+    }
+    return { route: 'page', path };
+  }
+  if (rest.startsWith('request/') && method === 'POST') {
+    const segments = decodeSegments(rest.slice('request/'.length));
+    if (segments.length < 2) {
+      return null;
+    }
+    return {
+      route: 'request',
+      pageId: segments.slice(0, -1).join('/'),
+      requestId: segments[segments.length - 1],
+    };
+  }
+  if (rest.startsWith('endpoints/')) {
+    const segments = decodeSegments(rest.slice('endpoints/'.length));
+    if (segments.length === 0) {
+      return null;
+    }
+    return { route: 'endpoint', endpointId: segments.join('/') };
+  }
+  return null;
+}
+
+export default matchJourneyRoute;

package/lib/docs/matchJourneyRoute.test.mjs

@@ -0,0 +1,178 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import createNetworkCounter from './createNetworkCounter.js';
+import matchExercisedPages from './matchExercisedPages.js';
+import matchJourneyRoute from './matchJourneyRoute.js';
+import mergeNetworkSnapshots from './mergeNetworkSnapshots.js';
+import nextJourneySequence from './nextJourneySequence.js';
+
+const origin = 'http://localhost:3111';
+
+test.each([
+  ['GET', '/api/root', { route: 'root' }],
+  ['GET', '/api/page/tickets', { route: 'page', path: 'tickets' }],
+  ['GET', '/api/page/admin/users', { route: 'page', path: 'admin/users' }],
+  ['GET', '/api/page/tickets/s/2', { route: 'page', path: 'tickets/s/2' }],
+  ['GET', '/api/page/', null],
+  [
+    'POST',
+    '/api/request/tickets/assign',
+    { route: 'request', pageId: 'tickets', requestId: 'assign' },
+  ],
+  ['POST', '/api/endpoints/notify', { route: 'endpoint', endpointId: 'notify' }],
+  ['GET', '/api/endpoints/reports/daily', { route: 'endpoint', endpointId: 'reports/daily' }],
+  ['POST', '/api/root', null],
+  ['GET', '/api/request/tickets/assign', null],
+  ['POST', '/api/request/tickets', null],
+  ['GET', '/api/reload', null],
+  ['GET', '/tickets', null],
+])('matchJourneyRoute matches %s %s', (method, pathname, expected) => {
+  expect(matchJourneyRoute({ url: `${origin}${pathname}`, method, origin })).toEqual(expected);
+});
+
+test('matchJourneyRoute honours the basePath and ignores paths outside it', () => {
+  expect(
+    matchJourneyRoute({
+      url: `${origin}/app/api/page/home`,
+      method: 'GET',
+      origin,
+      basePath: '/app',
+    })
+  ).toEqual({ route: 'page', path: 'home' });
+  expect(
+    matchJourneyRoute({
+      url: `${origin}/app/api/page/tickets/s/2?tab=notes`,
+      method: 'GET',
+      origin,
+      basePath: '/app',
+    })
+  ).toEqual({ route: 'page', path: 'tickets/s/2' });
+  expect(
+    matchJourneyRoute({ url: `${origin}/api/page/home`, method: 'GET', origin, basePath: '/app' })
+  ).toBeNull();
+});
+
+test('matchJourneyRoute ignores requests to another origin', () => {
+  expect(
+    matchJourneyRoute({ url: 'http://elsewhere.test/api/page/home', method: 'GET', origin })
+  ).toBeNull();
+});
+
+function request(method, pathname) {
+  return { method: () => method, url: () => `${origin}${pathname}` };
+}
+
+test('createNetworkCounter counts request calls per page and endpoint calls', () => {
+  const counter = createNetworkCounter({ origin, basePath: '' });
+  counter.record(request('GET', '/api/root'));
+  counter.record(request('GET', '/api/page/tickets'));
+  counter.record(request('GET', '/api/page/tickets/s/2'));
+  counter.record(request('POST', '/api/request/tickets/save'));
+  counter.record(request('POST', '/api/request/tickets/save'));
+  counter.record(request('POST', '/api/request/ticket/save'));
+  counter.record(request('POST', '/api/endpoints/notify'));
+  expect(counter.countCalls({ request: 'save', pageId: 'tickets' })).toEqual(2);
+  expect(counter.countCalls({ request: 'save', pageId: 'ticket' })).toEqual(1);
+  expect(counter.countCalls({ request: 'save', pageId: 'other' })).toEqual(0);
+  expect(counter.countCalls({ endpoint: 'notify' })).toEqual(1);
+  expect(counter.countCalls({ endpoint: 'other' })).toEqual(0);
+  expect(counter.snapshot()).toEqual({
+    pagePaths: ['tickets', 'tickets/s/2'],
+    appEvents: true,
+    requests: [
+      { pageId: 'tickets', requestId: 'save', calls: 2 },
+      { pageId: 'ticket', requestId: 'save', calls: 1 },
+    ],
+    endpoints: [{ endpointId: 'notify', calls: 1 }],
+  });
+});
+
+test('mergeNetworkSnapshots sums calls across actors and sorts the result', () => {
+  expect(
+    mergeNetworkSnapshots({
+      snapshots: [
+        {
+          pagePaths: ['tickets/s/2'],
+          appEvents: true,
+          requests: [{ pageId: 'tickets', requestId: 'save', calls: 1 }],
+          endpoints: [{ endpointId: 'notify', calls: 1 }],
+        },
+        {
+          pagePaths: ['home', 'tickets/s/2', 'tickets/s/5'],
+          appEvents: false,
+          requests: [
+            { pageId: 'tickets', requestId: 'save', calls: 2 },
+            { pageId: 'home', requestId: 'load', calls: 1 },
+          ],
+          endpoints: [{ endpointId: 'notify', calls: 3 }],
+        },
+      ],
+    })
+  ).toEqual({
+    pagePaths: ['home', 'tickets/s/2', 'tickets/s/5'],
+    appEvents: true,
+    requests: [
+      { pageId: 'home', requestId: 'load', calls: 1 },
+      { pageId: 'tickets', requestId: 'save', calls: 3 },
+    ],
+    endpoints: [{ endpointId: 'notify', calls: 4 }],
+  });
+});
+
+const routes = [
+  { pageId: 'home', path: 'home' },
+  { pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' },
+  { pageId: 'admin/users', path: 'people' },
+];
+
+test('matchExercisedPages names a patterned page once for all of its instances', () => {
+  expect(
+    matchExercisedPages({ routes, pagePaths: ['tickets/s/2', 'tickets/s/5', 'home'] })
+  ).toEqual(['home', 'ticket']);
+});
+
+test('matchExercisedPages names a page with a fixed path by its id', () => {
+  expect(matchExercisedPages({ routes, pagePaths: ['people'] })).toEqual(['admin/users']);
+});
+
+test('matchExercisedPages drops a path no page answers', () => {
+  expect(matchExercisedPages({ routes, pagePaths: ['admin/users', 'missing'] })).toEqual([]);
+});
+
+test('a journey under a basePath reports page ids for the page paths it loaded', () => {
+  const counter = createNetworkCounter({ origin, basePath: '/app' });
+  counter.record(request('GET', '/app/api/page/tickets/s/2'));
+  counter.record(request('GET', '/app/api/page/people'));
+  counter.record(request('GET', '/api/page/home'));
+  expect(
+    matchExercisedPages({
+      routes,
+      pagePaths: mergeNetworkSnapshots({ snapshots: [counter.snapshot()] }).pagePaths,
+    })
+  ).toEqual(['admin/users', 'ticket']);
+});
+
+test('the network counter tells a request call made after a point from one made before it', () => {
+  const counter = createNetworkCounter({ origin, basePath: '' });
+  const call = { url: () => `${origin}/api/request/form/save`, method: () => 'POST' };
+  const beforeCall = nextJourneySequence();
+  counter.record(call);
+  const afterCall = nextJourneySequence();
+  expect(counter.calledSince({ request: 'save', pageId: 'form', since: beforeCall })).toBe(true);
+  expect(counter.calledSince({ request: 'save', pageId: 'form', since: afterCall })).toBe(false);
+  expect(counter.calledSince({ request: 'load', pageId: 'form', since: 0 })).toBe(false);
+});

package/lib/docs/mergeNetworkSnapshots.js

@@ -0,0 +1,49 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// One journey's network path across all of its actors: the request path of a
+// page any actor loaded, and each request or endpoint with the calls of every actor summed.
+function mergeNetworkSnapshots({ snapshots }) {
+  const pagePaths = new Set();
+  const requests = new Map();
+  const endpoints = new Map();
+  let appEvents = false;
+  snapshots.forEach((snapshot) => {
+    snapshot.pagePaths.forEach((path) => pagePaths.add(path));
+    appEvents = appEvents || snapshot.appEvents;
+    snapshot.requests.forEach(({ pageId, requestId, calls }) => {
+      const key = JSON.stringify([pageId, requestId]);
+      const entry = requests.get(key) ?? { pageId, requestId, calls: 0 };
+      entry.calls += calls;
+      requests.set(key, entry);
+    });
+    snapshot.endpoints.forEach(({ endpointId, calls }) => {
+      endpoints.set(endpointId, (endpoints.get(endpointId) ?? 0) + calls);
+    });
+  });
+  return {
+    pagePaths: [...pagePaths].sort(),
+    appEvents,
+    requests: [...requests.values()].sort(
+      (a, b) => a.pageId.localeCompare(b.pageId) || a.requestId.localeCompare(b.requestId)
+    ),
+    endpoints: [...endpoints.entries()]
+      .map(([endpointId, calls]) => ({ endpointId, calls }))
+      .sort((a, b) => a.endpointId.localeCompare(b.endpointId)),
+  };
+}
+
+export default mergeNetworkSnapshots;

package/lib/docs/nextJourneySequence.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// One ordering for every journey's network events and step windows in this
+// process. A clock can give a call and the step after it the same millisecond;
+// a sequence cannot, so "started since the step began" is never a tie. Kept on
+// globalThis, as journeyActor.js keeps its token, so two module instances of
+// this file (Vite's SSR module graph and Node's) still share one order.
+const SEQUENCE_KEY = Symbol.for('lowdefy.devServer.journeySequence');
+globalThis[SEQUENCE_KEY] ??= 0;
+
+function nextJourneySequence() {
+  globalThis[SEQUENCE_KEY] += 1;
+  return globalThis[SEQUENCE_KEY];
+}
+
+export default nextJourneySequence;

package/lib/docs/noBrowserError.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The message every browser tool returns when getBrowser() fails.
+function noBrowserError(error) {
+  return `No Chromium available. Run: npx playwright install chromium-headless-shell (the dev server installs it on first use unless PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is set). ${error.message}`;
+}
+
+export default noBrowserError;

package/lib/docs/observe/TRANSIENT_SELECTOR.js

@@ -0,0 +1,21 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// antd's click wave: inserted into a clicked Button and removed when its
+// motion ends, so a step window's mutation count never counts it.
+const TRANSIENT_SELECTOR = '.ant-wave';
+
+export default TRANSIENT_SELECTOR;

package/lib/docs/observe/claimExpectedErrors.js

@@ -0,0 +1,67 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import toAppErrorFailure from './toAppErrorFailure.js';
+
+function describeErrors(findings) {
+  if (findings.length === 0) {
+    return 'no app error';
+  }
+  return findings.map((finding) => `${finding.kind}: ${finding.message}`);
+}
+
+function matches({ finding, text }) {
+  return String(finding.message).includes(text);
+}
+
+// An expect.error step claims the app errors of the interaction just before
+// it (held) and of its own window whose message contains its text. Returns
+// the failure, or undefined when the claim passes: the expect step fails when
+// no error matches, and the interaction fails on any error left unclaimed.
+//
+// An action-error is the trace's account of the action that failed, and the
+// trace is value-free: its message names the action and the error class, never
+// the error's text. So once an error with the text is claimed, the failed
+// action that reported it is claimed with it. An event stops at its first
+// failed action, so this claims no second, unrelated failure of the event.
+function claimExpectedErrors({ step, index, held, findings }) {
+  const text = step.expect.error;
+  const seen = [...(held?.findings ?? []), ...findings];
+  const matched = seen.filter((finding) => matches({ finding, text }));
+  const claimed =
+    matched.length === 0
+      ? []
+      : seen.filter((finding) => matches({ finding, text }) || finding.kind === 'action-error');
+  if (claimed.length === 0) {
+    const actual = describeErrors(seen);
+    return {
+      index,
+      step,
+      expected: `an app error containing "${text}"`,
+      actual,
+      message: `Expected an app error containing "${text}" but found ${
+        seen.length === 0 ? 'no app error.' : actual.join('; ')
+      }`,
+    };
+  }
+  const unclaimed = seen.filter((finding) => !claimed.includes(finding));
+  if (unclaimed.length === 0) {
+    return undefined;
+  }
+  return toAppErrorFailure({ findings: unclaimed, index: held.index, step: held.step });
+}
+
+export default claimExpectedErrors;