@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/createDocsMcpServerRunJourney.test.mjs

@@ -0,0 +1,148 @@
+/*
+  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 { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+
+import { jest } from '@jest/globals';
+
+import setupTestFixtures from './setupTestFixtures.mjs';
+
+const fixtureDir = setupTestFixtures();
+process.chdir(fixtureDir);
+
+// An app served under a basePath: lowdefy_run_journey must hand it to the
+// runner, which counts calls and app errors under it.
+jest.unstable_mockModule('../build/config.js', () => ({ default: { basePath: '/app' } }));
+const mockRunJourney = jest.fn();
+jest.unstable_mockModule('./runJourney.js', () => ({ default: mockRunJourney }));
+
+const { default: createDocsMcpServer } = await import('./createDocsMcpServer.js');
+
+async function connectClient() {
+  const server = createDocsMcpServer({ origin: 'http://localhost:3000', version: '7.2.0' });
+  const client = new Client({ name: 'test-client', version: '1.0.0' });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  return client;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockRunJourney.mockResolvedValue({ pageId: 'ticket', passed: true, steps: [], screenshots: [] });
+});
+
+test('MCP lowdefy_run_journey passes pathParams and the basePath to every run of a user list', async () => {
+  const client = await connectClient();
+
+  await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: {
+      pageId: 'ticket',
+      pathParams: { ticket_id: 't1' },
+      steps: [],
+      data: 'crm',
+      user: ['admin', 'member'],
+    },
+  });
+
+  expect(mockRunJourney).toHaveBeenCalledTimes(2);
+  mockRunJourney.mock.calls.forEach(([params]) => {
+    expect(params).toEqual(
+      expect.objectContaining({
+        pageId: 'ticket',
+        pathParams: { ticket_id: 't1' },
+        data: 'crm',
+        basePath: '/app',
+      })
+    );
+  });
+  await client.close();
+});
+
+test('MCP lowdefy_run_journey passes pathParams and the basePath to a single run', async () => {
+  const client = await connectClient();
+
+  await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'ticket', pathParams: { ticket_id: 't1' }, steps: [] },
+  });
+
+  expect(mockRunJourney).toHaveBeenCalledWith(
+    expect.objectContaining({ pathParams: { ticket_id: 't1' }, basePath: '/app' })
+  );
+  await client.close();
+});
+
+const fullExercised = {
+  pages: [{ pageId: 'ticket' }],
+  requests: [{ id: 'get_a' }, { id: 'get_b' }],
+  endpoints: [],
+  events: [{ id: 'e1' }, { id: 'e2' }, { id: 'e3' }],
+  rendered: [{ blockId: 'a' }],
+  unfollowed: [],
+};
+
+async function callWith(extra, user) {
+  mockRunJourney.mockResolvedValue({
+    pageId: 'ticket',
+    passed: true,
+    steps: [],
+    screenshots: [],
+    exercised: fullExercised,
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'ticket', steps: [], ...(user ? { user, data: 'crm' } : {}), ...extra },
+  });
+  await client.close();
+  return JSON.parse(result.content[0].text);
+}
+
+test('MCP lowdefy_run_journey returns a count of each exercised list by default', async () => {
+  const body = await callWith({});
+  expect(body.exercised.counts).toEqual({
+    pages: 1,
+    requests: 2,
+    endpoints: 0,
+    events: 3,
+    rendered: 1,
+    unfollowed: 0,
+  });
+  expect(body.exercised.requests).toBeUndefined();
+});
+
+test('MCP lowdefy_run_journey returns the full exercised block with exercised: true', async () => {
+  const body = await callWith({ exercised: true });
+  expect(body.exercised).toEqual(fullExercised);
+});
+
+test('MCP lowdefy_run_journey leaves exercised out with exercised: false', async () => {
+  const body = await callWith({ exercised: false });
+  expect(body.exercised).toBeUndefined();
+});
+
+test('MCP lowdefy_run_journey applies exercised to every run of a user list', async () => {
+  const compact = await callWith({}, ['admin', 'member']);
+  expect(compact.runs).toHaveLength(2);
+  compact.runs.forEach((run) => expect(run.exercised.counts.events).toBe(3));
+  const none = await callWith({ exercised: false }, ['admin', 'member']);
+  none.runs.forEach((run) => expect(run.exercised).toBeUndefined());
+  const full = await callWith({ exercised: true }, ['admin', 'member']);
+  full.runs.forEach((run) => expect(run.exercised).toEqual(fullExercised));
+});

package/lib/docs/createJourneyActors.chromium.test.mjs

@@ -0,0 +1,227 @@
+/*
+  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 http from 'node:http';
+
+import { jest } from '@jest/globals';
+
+import pageReadyScript from '../../test-utils/pageReadyScript.mjs';
+
+// A real Chromium against a small server that answers the dev server's own
+// routes, so the context-level request listener is exercised as a journey
+// runs it: installed before the first navigation, and still counting after a
+// full page load. Skipped when no Chromium can be launched.
+jest.unstable_mockModule('../build/config.js', () => ({ default: {} }));
+
+const { getBrowser } = await import('./getBrowser.js');
+const { default: createJourneyActors } = await import('./createJourneyActors.js');
+
+function pageHtml(script) {
+  return `<!doctype html><html><head><title>loading</title></head><body><script>${script}</script></body></html>`;
+}
+
+const recorderPosts = [];
+
+// Each page marks itself ready once its requests finish (pageReadyScript), so
+// openPage returns then instead of waiting out its timeout.
+const pages = {
+  '/recorded': pageHtml(`
+    window.__lowdefyRecorder = {
+      flush: () => fetch('/api/dev-recording', { method: 'POST', body: JSON.stringify({ actor: document.cookie }) }),
+    };
+    ${pageReadyScript({ pageId: 'recorded' })}
+    document.title = 'recorded-ready';
+  `),
+  '/first': pageHtml(`
+    fetch('/api/root')
+      .then(() => fetch('/api/page/first'))
+      .then(() => fetch('/api/request/first/save', { method: 'POST' }))
+      .then(() => fetch('/api/endpoints/notify', { method: 'POST' }))
+      .then(() => {
+        ${pageReadyScript({ pageId: 'first' })}
+        document.title = 'first-done';
+      });
+  `),
+  '/second': pageHtml(`
+    fetch('/api/page/second')
+      .then(() => fetch('/api/request/first/save', { method: 'POST' }))
+      .then(() => {
+        ${pageReadyScript({ pageId: 'second' })}
+        document.title = 'second-done';
+      });
+  `),
+};
+
+// A cold Chromium on a Windows runner can take seconds over the first
+// navigation; what is pinned here is what the actors count, not page speed.
+const PAGE_TIMEOUT = 15000;
+
+let server;
+let origin;
+let browser = null;
+try {
+  browser = await getBrowser();
+} catch {
+  browser = null;
+}
+const chromiumTest = browser === null ? test.skip : test;
+
+beforeAll(async () => {
+  server = http.createServer((req, res) => {
+    if (req.url === '/api/dev-recording') {
+      recorderPosts.push({ cookie: req.headers.cookie ?? '' });
+    }
+    const html = pages[req.url];
+    if (html !== undefined) {
+      res.writeHead(200, { 'content-type': 'text/html' });
+      res.end(html);
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end('{}');
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  origin = `http://127.0.0.1:${server.address().port}`;
+});
+
+// Closing Chromium on Windows can take longer than Jest's 5 s hook default.
+afterAll(async () => {
+  await browser?.close();
+  server.closeAllConnections();
+  await new Promise((resolve) => server.close(resolve));
+}, 30000);
+
+chromiumTest(
+  'journey actors count pages, request calls, endpoints and app events across a full page load',
+  async () => {
+    const actors = createJourneyActors({
+      browser,
+      origin,
+      basePath: '',
+      pageId: 'first',
+      user: 'none',
+      timeout: PAGE_TIMEOUT,
+    });
+    try {
+      const { page } = await actors.switchTo('main');
+      await page.waitForFunction(() => document.title === 'first-done');
+      await page.goto(`${origin}/second`);
+      await page.waitForFunction(() => document.title === 'second-done');
+
+      expect(actors.countCalls({ request: 'save', pageId: 'first' })).toEqual(2);
+      expect(actors.countCalls({ endpoint: 'notify' })).toEqual(1);
+      expect(actors.networkSnapshots()).toEqual([
+        {
+          pagePaths: ['first', 'second'],
+          appEvents: true,
+          requests: [{ pageId: 'first', requestId: 'save', calls: 2 }],
+          endpoints: [{ endpointId: 'notify', calls: 1 }],
+        },
+      ]);
+    } finally {
+      await actors.closeAll();
+    }
+  },
+  30000
+);
+
+chromiumTest(
+  'a second journey actor counts its own requests apart from the first',
+  async () => {
+    const actors = createJourneyActors({
+      browser,
+      origin,
+      basePath: '',
+      pageId: 'second',
+      user: 'none',
+      timeout: PAGE_TIMEOUT,
+    });
+    try {
+      const main = await actors.switchTo('main');
+      await main.page.waitForFunction(() => document.title === 'second-done');
+      const other = await actors.switchTo('other');
+      await other.page.waitForFunction(() => document.title === 'second-done');
+      await other.page.reload();
+      await other.page.waitForFunction(() => document.title === 'second-done');
+      expect(actors.countCalls({ request: 'save', pageId: 'first' })).toEqual(2);
+      await actors.switchTo('main');
+      expect(actors.countCalls({ request: 'save', pageId: 'first' })).toEqual(1);
+    } finally {
+      await actors.closeAll();
+    }
+  },
+  30000
+);
+
+chromiumTest(
+  'recording actors carry a recording cookie with their actor name and flush before closing',
+  async () => {
+    const { default: readRecordingCookie } = await import(
+      '../server/recording/readRecordingCookie.js'
+    );
+    const actors = createJourneyActors({
+      browser,
+      origin,
+      basePath: '',
+      pageId: 'recorded',
+      user: 'none',
+      timeout: PAGE_TIMEOUT,
+      recording: {
+        source: 'journey',
+        run: { id: '20261003T151200Z-p0d4rm', by: 'test', journey: 'tests/journeys/a.yaml' },
+      },
+    });
+    try {
+      const { page } = await actors.switchTo('main');
+      await page.waitForFunction(() => document.title === 'recorded-ready');
+      await actors.switchTo('invitee');
+      await actors.flushRecordings();
+    } finally {
+      await actors.closeAll();
+    }
+    expect(recorderPosts).toHaveLength(2);
+    const runs = recorderPosts
+      .map(({ cookie }) => readRecordingCookie(cookie))
+      .map((recording) => recording.run.actor)
+      .sort();
+    expect(runs).toEqual(['invitee', 'main']);
+  },
+  30000
+);
+
+chromiumTest(
+  'a non-recording actor is marked off and a page with no recorder flushes without error',
+  async () => {
+    const actors = createJourneyActors({
+      browser,
+      origin,
+      basePath: '',
+      pageId: 'second',
+      user: 'none',
+      timeout: PAGE_TIMEOUT,
+    });
+    try {
+      const { context } = await actors.switchTo('main');
+      const cookies = await context.cookies();
+      const recording = cookies.find((cookie) => cookie.name === 'lowdefy_recording');
+      expect(recording.value.endsWith('.off')).toBe(true);
+      await expect(actors.flushRecordings()).resolves.toBeUndefined();
+    } finally {
+      await actors.closeAll();
+    }
+  },
+  30000
+);

package/lib/docs/createJourneyActors.js

@@ -0,0 +1,213 @@
+/*
+  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 collectVisibleBlockIds from '../client/collectVisibleBlockIds.js';
+import createJourneyObservations from './createJourneyObservations.js';
+import createNetworkCounter from './createNetworkCounter.js';
+import { openPage } from './getBrowser.js';
+
+// The binding client/JourneyObserver.jsx looks for. A binding exists in every
+// document of the context it is exposed on, across full page loads, and in no
+// developer tab, so only a journey's own pages report what they ran.
+const OBSERVE_BINDING = '__lowdefyJourneyObserve';
+
+let actorCount = 0;
+
+// Every actor is its own client, as two people on two devices are: auth rate
+// limits count attempts per client address, and a whole suite run from one
+// machine would otherwise share a single budget, so the tenth journey's
+// sign-in fails with "Too many requests" because of the nine before it. Each
+// actor gets the next address in 203.0.113.0/24 (reserved for documentation,
+// never a real client), so one actor's rapid attempts are still limited the
+// way one person's are.
+function nextClientAddress() {
+  actorCount += 1;
+  return `203.0.113.${((actorCount - 1) % 254) + 1}`;
+}
+
+// The people a journey acts as, each in its own browser context with its own
+// cookie jar, so an owner and an invitee - or a member whose session stays
+// open while the owner removes them - are signed in at the same time. An
+// actor opens the journey's page, as the journey's user (or as the data set
+// user of that name), the first time its name is switched to, and keeps its
+// tab as it left it when the journey switches away and back. Every actor sees
+// the same viewport and colour scheme. Each actor's context feeds its own
+// network counter from before its first navigation, so what the journey
+// touched is measured per actor and merged at the end. Each actor's pages also report, through the observe
+// binding, the events that completed and the blocks that were ever visible,
+// into one set of observations for the whole journey.
+function createJourneyActors({
+  browser,
+  origin,
+  basePath,
+  pageId,
+  path,
+  pathParams,
+  user,
+  urlQuery,
+  width,
+  height,
+  colorScheme,
+  timeout,
+  dataCookie,
+  mutantCookie,
+  users = {},
+  mainActor,
+  recording,
+  onContext,
+}) {
+  const actors = new Map();
+  const counters = new Map();
+  const observations = createJourneyObservations();
+  let currentName;
+
+  // An actor named after a data set user opens as that user; the journey's
+  // first actor, and any other name, opens as the journey's user.
+  function userFor(name) {
+    if (name !== mainActor && Object.prototype.hasOwnProperty.call(users, name)) {
+      return users[name];
+    }
+    return user;
+  }
+
+  async function switchTo(name) {
+    if (!actors.has(name)) {
+      const counter = createNetworkCounter({ origin, basePath });
+      counters.set(name, counter);
+      const opened = await openPage({
+        browser,
+        origin,
+        pageId,
+        path,
+        pathParams,
+        user: userFor(name),
+        urlQuery,
+        width,
+        height,
+        colorScheme,
+        clientAddress: nextClientAddress(),
+        dataCookie,
+        mutantCookie,
+        recording: type.isUndefined(recording)
+          ? undefined
+          : { ...recording, run: { ...recording.run, actor: name } },
+        onContext: async (context) => {
+          context.on('request', (request) => counter.record(request));
+          await context.exposeBinding(OBSERVE_BINDING, (source, message) =>
+            observations.receive(message)
+          );
+          // A caller that watches each actor's context (a journey run's app
+          // error buffers) hooks in before its first request.
+          if (!type.isUndefined(onContext)) {
+            onContext({ context, name });
+          }
+        },
+        timeout,
+      });
+      actors.set(name, opened);
+    }
+    currentName = name;
+    return actors.get(name);
+  }
+
+  function current() {
+    return actors.get(currentName);
+  }
+
+  function countCalls(query) {
+    return counters.get(currentName).countCalls(query);
+  }
+
+  function calledSince(query) {
+    return counters.get(currentName).calledSince(query);
+  }
+
+  // The first URL any actor's context tried to reach on another host of the dev server, which a
+  // data set journey must never do (see guardJourneyOrigin).
+  function leftOrigin() {
+    for (const opened of actors.values()) {
+      if (opened.leftOrigin.length > 0) {
+        return opened.leftOrigin[0];
+      }
+    }
+    return undefined;
+  }
+
+  function networkSnapshots() {
+    return [...counters.values()].map((counter) => counter.snapshot());
+  }
+
+  // The runner's own look at the current page once a step has settled, beside
+  // the observer's samples on every DOM change. A page that is navigating or
+  // has crashed has nothing to report.
+  async function sampleRendered() {
+    const { page } = current();
+    try {
+      const pageId = await page.evaluate(() => window.lowdefy?.pageId);
+      const blockIds = await page.evaluate(collectVisibleBlockIds);
+      observations.receive({ kind: 'rendered', pageId, blockIds });
+    } catch {
+      // Nothing to sample.
+    }
+  }
+
+  function observed() {
+    return observations.snapshot();
+  }
+
+  // Closing a context does not reliably fire pagehide, so each actor's dev
+  // recorder is flushed first, or the journey's last steps would be lost.
+  async function flushRecordings({ capMs = 2000 } = {}) {
+    await Promise.all(
+      [...actors.values()].map(async ({ page }) => {
+        // Cleared once the race settles, so a flush that wins does not leave
+        // the cap's timer holding the process open.
+        let cap;
+        try {
+          await Promise.race([
+            page.evaluate(() => window.__lowdefyRecorder?.flush()).catch(() => {}),
+            new Promise((resolve) => {
+              cap = setTimeout(resolve, capMs);
+            }),
+          ]);
+        } finally {
+          clearTimeout(cap);
+        }
+      })
+    );
+  }
+
+  async function closeAll() {
+    await Promise.all([...actors.values()].map(({ context }) => context.close().catch(() => {})));
+  }
+
+  return {
+    switchTo,
+    current,
+    countCalls,
+    calledSince,
+    leftOrigin,
+    networkSnapshots,
+    sampleRendered,
+    observed,
+    flushRecordings,
+    closeAll,
+  };
+}
+
+export default createJourneyActors;

package/lib/docs/createJourneyActors.test.mjs

@@ -0,0 +1,79 @@
+/*
+  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 { jest } from '@jest/globals';
+
+const mockOpenPage = jest.fn();
+jest.unstable_mockModule('./getBrowser.js', () => ({ openPage: mockOpenPage }));
+
+const { default: createJourneyActors } = await import('./createJourneyActors.js');
+
+beforeEach(() => {
+  mockOpenPage.mockReset();
+  mockOpenPage.mockImplementation(async ({ user }) => ({
+    context: { close: jest.fn(async () => {}) },
+    page: {},
+    user,
+  }));
+});
+
+const users = {
+  main: { id: 'u_main', roles: ['member'] },
+  outsider: { id: 'u_9', roles: ['admin'], organizationId: 'org_b' },
+};
+
+function create(overrides) {
+  return createJourneyActors({
+    browser: {},
+    origin: 'http://localhost:3227',
+    basePath: '',
+    pageId: 'tickets',
+    user: { id: 'u_1', roles: ['admin'] },
+    dataCookie: 'session1',
+    users,
+    mainActor: 'main',
+    ...overrides,
+  });
+}
+
+test('switchTo opens an actor named after a data set user as that user, with the data cookie', async () => {
+  const actors = create();
+  await actors.switchTo('outsider');
+  expect(mockOpenPage).toHaveBeenCalledWith(
+    expect.objectContaining({ user: users.outsider, dataCookie: 'session1' })
+  );
+});
+
+test('switchTo opens the main actor and any other name as the journey user', async () => {
+  const actors = create();
+  await actors.switchTo('main');
+  await actors.switchTo('reviewer');
+  expect(mockOpenPage.mock.calls.map(([options]) => options.user)).toEqual([
+    { id: 'u_1', roles: ['admin'] },
+    { id: 'u_1', roles: ['admin'] },
+  ]);
+  expect(mockOpenPage.mock.calls.every(([options]) => options.dataCookie === 'session1')).toBe(
+    true
+  );
+});
+
+test('switchTo opens every actor as the journey user without data set users', async () => {
+  const actors = create({ users: undefined, dataCookie: undefined });
+  await actors.switchTo('outsider');
+  expect(mockOpenPage).toHaveBeenCalledWith(
+    expect.objectContaining({ user: { id: 'u_1', roles: ['admin'] }, dataCookie: undefined })
+  );
+});