@lowdefy/e2e-utils 6.1.0 → 7.1.0

package/README.md

@@ -321,6 +321,30 @@ export default createConfig({
 });
 ```
 
+The server Playwright starts stops when the Playwright run stops, however the run ends, so a killed or timed-out run leaves no server behind.
+
+| Variable                        | Effect                                                                                                                                                                                      |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOWDEFY_E2E_PORT`              | Runs on this port instead of the configured one, so two git worktrees can run the same suite at once.                                                                                       |
+| `LOWDEFY_E2E_REUSE_SERVER=true` | Reuses a server already running on the port (for example one started with `pnpm e2e:server`) instead of failing the run. The global setup still checks that it serves this app's e2e build. |
+
+## Starting a Server Outside Playwright
+
+`startServer` builds and starts an app's e2e server for other test runners (a vitest or Jest `globalSetup`) and scripts. The server stops when the process that called `startServer` exits, however it exits, so a killed or timed-out run leaves nothing behind.
+
+```javascript
+import startServer from '@lowdefy/e2e-utils/startServer';
+
+const server = await startServer({
+  appDir: './', // Where lowdefy.yaml is
+  port: 3191, // Fails at once if the port is already in use
+  env: { MY_SECRET: 'value' }, // Extra environment variables for the server
+  build: true, // Run `lowdefy build --server e2e` first (default: true)
+});
+// server.url === 'http://localhost:3191'
+await server.stop(); // SIGTERM, then SIGKILL after a grace period
+```
+
 ## Adding E2E Support to a Block
 
 Use `createBlockHelper` to define a block's e2e helper. Common methods (visible, hidden, disabled, enabled, validation) are auto-provided from the locator:

package/dist/config.js

@@ -14,8 +14,28 @@
   limitations under the License.
 */ import fs from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { defineConfig, devices } from '@playwright/test';
-function createConfig({ appDir = './', buildDir = '.lowdefy/server/build', commandPrefix = '', mocksFile = 'e2e/mocks.yaml', port = 3000, testDir = 'e2e', testMatch = '**/*.spec.js', timeout = 180000, screenshot = 'only-on-failure', outputDir = 'test-results' } = {}) {
+// Checks each reused or started server is this app's e2e build (see core/verifyServer.js).
+const globalSetup = fileURLToPath(new URL('./globalSetup.js', import.meta.url));
+// A server left running on the port (by a run that was killed, or another checkout) serves
+// the build it loaded, so it is reused only on request.
+function shouldReuseServer() {
+    return process.env.LOWDEFY_E2E_REUSE_SERVER === 'true';
+}
+// The server stops when this process does, however it ends: Playwright cleans up its web
+// servers only on a normal exit or SIGINT, so a killed or timed-out run would otherwise leave
+// the server behind. Playwright evaluates this config again in every worker, but only the
+// runner launches webServer, so the runner's pid is the one the server watches.
+function webServerEnv() {
+    return {
+        ...process.env,
+        LOWDEFY_EXIT_WITH_PID: String(process.pid)
+    };
+}
+function createConfig({ appDir = './', buildDir = '.lowdefy/server/build', commandPrefix = '', mocksFile = 'e2e/mocks.yaml', port: defaultPort = 3000, testDir = 'e2e', testMatch = '**/*.spec.js', timeout = 180000, screenshot = 'only-on-failure', outputDir = 'test-results' } = {}) {
+    // LOWDEFY_E2E_PORT moves a run, so two git worktrees can run the same suite at once.
+    const port = Number(process.env.LOWDEFY_E2E_PORT ?? defaultPort);
     // Resolve absolute paths for all directories
     const absoluteAppDir = path.resolve(appDir);
     // Use the local binary when available — npx may resolve the latest stable from npm
@@ -31,12 +51,19 @@ function createConfig({ appDir = './', buildDir = '.lowdefy/server/build', comma
     if (fs.existsSync(absoluteMocksFile)) {
         process.env.LOWDEFY_E2E_MOCKS_FILE = absoluteMocksFile;
     }
+    process.env.LOWDEFY_E2E_SERVERS = JSON.stringify([
+        {
+            buildDir: absoluteBuildDir,
+            port
+        }
+    ]);
     return defineConfig({
         testDir,
         testMatch,
         fullyParallel: true,
         reporter: 'list',
         outputDir,
+        globalSetup,
         use: {
             baseURL: `http://localhost:${port}`,
             trace: 'on-first-retry',
@@ -58,11 +85,12 @@ function createConfig({ appDir = './', buildDir = '.lowdefy/server/build', comma
         webServer: {
             // Build with e2e server and start
             command: `${cliCommand} build --server e2e && ${cliCommand} start --port ${port} --log-level warn`,
-            // Use session API for health check — page URLs may redirect when auth is configured
-            url: `http://localhost:${port}/api/auth/session`,
-            reuseExistingServer: true,
+            // A reused server must still pass globalSetup's check that it serves this app's e2e build.
+            port,
+            reuseExistingServer: shouldReuseServer(),
             timeout,
-            cwd: absoluteAppDir
+            cwd: absoluteAppDir,
+            env: webServerEnv()
         }
     });
 }
@@ -83,6 +111,10 @@ function createMultiAppConfig({ apps = [], commandPrefix = '', testDir = 'e2e',
             }
         };
     });
+    process.env.LOWDEFY_E2E_SERVERS = JSON.stringify(apps.map((app)=>({
+            buildDir: path.resolve(app.appDir, app.buildDir ?? '.lowdefy/server/build'),
+            port: app.port
+        })));
     // Set up webServers for each app
     const webServer = apps.map((app)=>{
         const appLocalBin = path.join(app.appDir, 'node_modules', '.bin', 'lowdefy');
@@ -90,11 +122,11 @@ function createMultiAppConfig({ apps = [], commandPrefix = '', testDir = 'e2e',
         const appCliCommand = `${commandPrefix ? `${commandPrefix} ` : ''}${appLowdefyCmd}`;
         return {
             command: `${appCliCommand} build --server e2e && ${appCliCommand} start --port ${app.port} --log-level warn`,
-            // Use session API for health check — page URLs may redirect when auth is configured
-            url: `http://localhost:${app.port}/api/auth/session`,
-            reuseExistingServer: true,
+            port: app.port,
+            reuseExistingServer: shouldReuseServer(),
             timeout,
-            cwd: app.appDir
+            cwd: app.appDir,
+            env: webServerEnv()
         };
     });
     return defineConfig({
@@ -102,6 +134,7 @@ function createMultiAppConfig({ apps = [], commandPrefix = '', testDir = 'e2e',
         fullyParallel: true,
         reporter: 'list',
         outputDir,
+        globalSetup,
         use: {
             trace: 'on-first-retry',
             screenshot,

package/dist/core/instanceKey.js

@@ -0,0 +1,32 @@
+/*
+  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.
+*/ // Browser-side expression: the context of the page instance on screen. The URL path, without the
+// basePath and one leading and one trailing slash (the form the client's path memory is keyed
+// by), is mapped to its instance through window.lowdefy.pathMemory, so two instances of one
+// patterned page are told apart. As the engine's lookupPath reads it, a path the memory has not
+// seen is the id of a page without a pattern; the app root shows the home page.
+const pageContextExpression = `(() => {
+  const lowdefy = window.lowdefy;
+  if (!lowdefy) return undefined;
+  const basePath = lowdefy.basePath ?? '';
+  let path = window.location.pathname;
+  if (basePath && path.startsWith(basePath)) path = path.slice(basePath.length);
+  path = path.replace(/^\\//, '').replace(/\\/$/, '');
+  const entry = lowdefy.pathMemory.get(path);
+  if (entry) return lowdefy.contexts[entry.instanceKey];
+  const pageId = path === '' ? lowdefy.home?.pageId : path;
+  return lowdefy.contexts['page:' + pageId];
+})()`;
+export default pageContextExpression;

package/dist/core/navigation.js

@@ -12,17 +12,34 @@
   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.
-*/ async function waitForReady(page) {
-    // Wait for Lowdefy client to initialize (context exists)
-    // Context key is "page:{pageId}" not just pageId
-    await page.waitForFunction(()=>{
-        const lowdefy = window.lowdefy;
-        return lowdefy && lowdefy.pageId && lowdefy.contexts[`page:${lowdefy.pageId}`];
-    }, {
+*/ import { buildPagePath, type, urlQuery } from '@lowdefy/helpers';
+import pageContextExpression from './instanceKey.js';
+async function waitForReady(page) {
+    // Wait for the context of the page instance on screen to exist.
+    await page.waitForFunction(`Boolean(${pageContextExpression})`, undefined, {
         timeout: 30000
     });
 }
-async function goto(page, path) {
+// A target is a URL path, or { basePath, pageId, path, pathParams, urlQuery } where `path` is
+// the page's path pattern (omit it for a page served at its id) and `basePath` the app's
+// config.basePath (omit it for an app served at the root). A string target is used as written,
+// so it carries its own basePath. The query is written as the app's links write it, so
+// `_url_query` reads back numbers, booleans and objects.
+function createPageUrl(target) {
+    if (type.isString(target)) {
+        return target;
+    }
+    const { basePath = '', pageId, path, pathParams, urlQuery: query } = target;
+    const pathname = `${basePath}/${buildPagePath({
+        pageId,
+        path,
+        pathParams
+    })}`;
+    const search = urlQuery.stringify(query);
+    return search ? `${pathname}?${search}` : pathname;
+}
+async function goto(page, target) {
+    const path = createPageUrl(target);
     // domcontentloaded is sufficient — waitForReady gates on the Lowdefy client
     // context, which is a stronger readiness signal than the browser 'load' event.
     // Using 'load' can hang when pages have WebSocket connections or slow resources.
@@ -31,10 +48,10 @@ async function goto(page, path) {
     });
     await waitForReady(page);
 }
-async function waitForPage(page, path) {
-    await page.waitForURL(path, {
+async function waitForPage(page, target) {
+    await page.waitForURL(createPageUrl(target), {
         waitUntil: 'domcontentloaded'
     });
     await waitForReady(page);
 }
-export { goto, waitForReady, waitForPage };
+export { createPageUrl, goto, waitForReady, waitForPage };

package/dist/core/readBasePath.js

@@ -0,0 +1,25 @@
+/*
+  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 fs from 'fs';
+import path from 'path';
+// The e2e server serves every route under the app's basePath, which the build records in
+// config.json. With no build yet (Playwright skips it when another server holds the
+// port), the server on the port cannot be this app's, and the root path is as good as any.
+function readBasePath({ buildDir }) {
+    const configFile = path.join(buildDir, 'config.json');
+    if (!fs.existsSync(configFile)) return '';
+    return JSON.parse(fs.readFileSync(configFile, 'utf8')).basePath ?? '';
+}
+export default readBasePath;

package/dist/core/requests.js

@@ -12,13 +12,12 @@
   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.
-*/ async function getRequestState(page, requestId) {
-    return page.evaluate((reqId)=>{
-        const lowdefy = window.lowdefy;
-        const pageId = lowdefy?.pageId;
-        const requests = lowdefy?.contexts?.[`page:${pageId}`]?.requests?.[reqId];
-        return requests?.[0];
-    }, requestId);
+*/ import pageContextExpression from './instanceKey.js';
+async function getRequestState(page, requestId) {
+    return page.evaluate(({ reqId, getContext })=>new Function(`return ${getContext}`)()?.requests?.[reqId]?.[0], {
+        reqId: requestId,
+        getContext: pageContextExpression
+    });
 }
 async function getRequestResponse(page, { requestId }) {
     const state = await getRequestState(page, requestId);

package/dist/core/state.js

@@ -12,12 +12,9 @@
   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.
-*/ async function getState(page) {
-    return page.evaluate(()=>{
-        const lowdefy = window.lowdefy;
-        const pageId = lowdefy?.pageId;
-        return lowdefy?.contexts?.[`page:${pageId}`]?.state;
-    });
+*/ import pageContextExpression from './instanceKey.js';
+async function getState(page) {
+    return page.evaluate(`${pageContextExpression}?.state`);
 }
 async function getBlockState(page, { blockId }) {
     const state = await getState(page);
@@ -27,15 +24,14 @@ async function setState(page, { key, value }) {
     // context.methods.setState does not exist on engine contexts - the engine's
     // action layer (see createSetState.js) writes state via State.set() and then
     // triggers a re-render via context._internal.update().
-    await page.evaluate(({ k, v })=>{
-        const lowdefy = window.lowdefy;
-        const pageId = lowdefy?.pageId;
-        const context = lowdefy?.contexts?.[`page:${pageId}`];
+    await page.evaluate(({ k, v, getContext })=>{
+        const context = new Function(`return ${getContext}`)();
         context._internal.State.set(k, v);
         context._internal.update();
     }, {
         k: key,
-        v: value
+        v: value,
+        getContext: pageContextExpression
     });
 }
 export { getState, getBlockState, setState };

package/dist/core/url.js

@@ -13,6 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { type } from '@lowdefy/helpers';
+import pageContextExpression from './instanceKey.js';
 import { waitForReady } from './navigation.js';
 // The client router's createUrl prepends basePath, so the pathname handed to it
 // must have basePath stripped or a basePath app receives it twice.
@@ -35,7 +36,7 @@ function createTargetLocation({ basePath = '', href, key, value }) {
 // resolved from the previous urlQuery. Routing through the router is what a
 // Link or SetUrlQuery action in the app does.
 async function setUrlQuery(page, { key, value }) {
-    const { basePath, dynamic, href } = await page.evaluate(()=>{
+    const { basePath, dynamic, href } = await page.evaluate((getContext)=>{
         const lowdefy = window.lowdefy;
         const router = lowdefy?._internal?.router;
         if (!router) {
@@ -43,26 +44,26 @@ async function setUrlQuery(page, { key, value }) {
         }
         return {
             basePath: router.basePath ?? '',
-            dynamic: lowdefy.contexts[`page:${lowdefy.pageId}`]?._internal?.pageConfig?.dynamic === true,
+            dynamic: new Function(`return ${getContext}`)()?._internal?.pageConfig?.dynamic === true,
             href: window.location.href
         };
-    });
-    // A router navigation always re-fetches the page config, and blocks reading
-    // _url_query re-render only once that config is applied. Listening starts
-    // before the navigation so the response cannot be missed.
-    const pageConfigFetched = page.waitForResponse((response)=>response.url().includes('/api/page/'), {
+    }, pageContextExpression);
+    // A query change re-fetches the page config only on a Dynamic page; a static
+    // page re-renders on the config it has. Listening starts before the
+    // navigation so the response cannot be missed.
+    const pageConfigFetched = dynamic ? page.waitForResponse((response)=>response.url().includes('/api/page/'), {
         timeout: 30000
     }).catch((error)=>{
         // A response that never arrives must not hang the suite — fall through and
         // let the test's own assertion report it. Anything else is a real fault.
         if (error.name !== 'TimeoutError') throw error;
-    });
+    }) : null;
     // A Dynamic page's content is resolved server-side from urlQuery, and the
     // engine rebuilds its context whenever a new config object arrives (see
     // getContext). Waiting for that rebuild proves the re-resolved content is in
     // place; the response arriving only proves it is on its way. Static pages keep
     // a memoized context, so there is no identity change to wait for.
-    const previousPageConfig = dynamic ? await page.evaluateHandle(()=>window.lowdefy.contexts[`page:${window.lowdefy.pageId}`]._internal.pageConfig) : null;
+    const previousPageConfig = dynamic ? await page.evaluateHandle(`${pageContextExpression}._internal.pageConfig`) : null;
     await page.evaluate(({ pathname, query })=>{
         // scroll: false keeps the viewport where it was — a query change is not a
         // page navigation from the test's point of view.
@@ -79,7 +80,10 @@ async function setUrlQuery(page, { key, value }) {
     }));
     await pageConfigFetched;
     if (previousPageConfig) {
-        await page.waitForFunction((previous)=>window.lowdefy.contexts[`page:${window.lowdefy.pageId}`]?._internal?.pageConfig !== previous, previousPageConfig, {
+        await page.waitForFunction(({ previous, getContext })=>new Function(`return ${getContext}`)()?._internal?.pageConfig !== previous, {
+            previous: previousPageConfig,
+            getContext: pageContextExpression
+        }, {
             timeout: 30000
         });
         await previousPageConfig.dispose();

package/dist/core/validation.js

@@ -12,13 +12,14 @@
   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.
-*/ async function getValidation(page, blockId) {
-    return page.evaluate((id)=>{
-        const lowdefy = window.lowdefy;
-        const pageId = lowdefy?.pageId;
-        const context = lowdefy?.contexts?.[`page:${pageId}`];
-        const block = context?._internal?.RootSlots?.map?.[id];
-        return block?.validationEval?.output;
-    }, blockId);
+*/ import pageContextExpression from './instanceKey.js';
+async function getValidation(page, blockId) {
+    return page.evaluate(({ id, getContext })=>{
+        const context = new Function(`return ${getContext}`)();
+        return context?._internal?.RootSlots?.map?.[id]?.validationEval?.output;
+    }, {
+        id: blockId,
+        getContext: pageContextExpression
+    });
 }
 export { getValidation };

package/dist/core/verifyServer.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.
+*/ import fs from 'fs';
+import readBasePath from './readBasePath.js';
+async function readIdentity({ identityPath, port }) {
+    let response;
+    try {
+        response = await fetch(`http://localhost:${port}${identityPath}`, {
+            signal: AbortSignal.timeout(10000)
+        });
+    } catch (error) {
+        throw new Error(`Could not reach the e2e server on port ${port}: ${error.message}`);
+    }
+    if (!response.ok) return null;
+    return response.json().catch(()=>null);
+}
+// Playwright reuses whatever server listens on the port. Only this app's e2e build applies
+// the request mocks and e2e session, so any other server (lowdefy dev, a production build,
+// another checkout's e2e server) must stop the run instead of being tested by accident.
+async function verifyServer({ buildDir, port }) {
+    const identityPath = `${readBasePath({
+        buildDir
+    })}/api/e2e/identity`;
+    const identity = await readIdentity({
+        identityPath,
+        port
+    });
+    const change = `Stop that server or set another \`port\` in the Playwright config`;
+    if (identity?.server !== 'lowdefy-e2e') {
+        throw new Error(`Port ${port} is in use by a server that is not a Lowdefy e2e server (${identityPath} did not answer as one), for example \`lowdefy dev\`. ${change}, so the tests run against this app's e2e build.`);
+    }
+    const expected = fs.existsSync(buildDir) ? fs.realpathSync(buildDir) : buildDir;
+    if (identity.buildDirectory !== expected) {
+        throw new Error(`Port ${port} is in use by the Lowdefy e2e server of another app or checkout, which serves ${identity.buildDirectory}. ${change}, so the tests run against this app's e2e build in ${expected}.`);
+    }
+}
+export default verifyServer;

package/dist/globalSetup.js

@@ -0,0 +1,24 @@
+/*
+  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 verifyServer from './core/verifyServer.js';
+// Playwright runs global setup after the webServer entries are up, whether it started
+// them or reused servers already running.
+async function globalSetup() {
+    const servers = JSON.parse(process.env.LOWDEFY_E2E_SERVERS ?? '[]');
+    for (const server of servers){
+        await verifyServer(server);
+    }
+}
+export default globalSetup;

package/dist/index.js

@@ -52,3 +52,6 @@ export { createBlockHelper, createHelperRegistry, createBlockMethodProxy, create
 // Mocking utilities
 import { createMockManager, loadStaticMocks } from './mocking/index.js';
 export { createMockManager, loadStaticMocks };
+// Server lifecycle for harnesses outside Playwright (vitest/Jest globalSetup, rig scripts)
+import startServer from './startServer.js';
+export { startServer };

package/dist/init/index.js

@@ -144,7 +144,7 @@ async function init() {
         console.log('     pnpm e2e            # Run all tests');
         console.log('     pnpm e2e:headed     # Run with visible browser');
         console.log('     pnpm e2e:ui         # Playwright UI mode');
-        console.log('     pnpm e2e:server     # Start server for reuse');
+        console.log('     pnpm e2e:server     # Start server for reuse (LOWDEFY_E2E_REUSE_SERVER=true pnpm e2e)');
     } else {
         for (const app of selectedApps){
             console.log(`     cd ${app.path} && pnpm e2e`);

package/dist/init/templates/README.md.template

@@ -21,12 +21,14 @@ By default, `pnpm e2e` does a full build before running tests. To skip the build
    pnpm e2e:server
    ```
 
-2. **Run tests** in another terminal — the config has `reuseExistingServer: true`, so Playwright detects the running server and skips the build:
+2. **Run tests** in another terminal with `LOWDEFY_E2E_REUSE_SERVER=true` — Playwright reuses the running server and skips the build. It only reuses this app's e2e server: if another server holds the port (for example `lowdefy dev`), the run stops with an error that names the port:
 
    ```bash
-   pnpm e2e
+   LOWDEFY_E2E_REUSE_SERVER=true pnpm e2e
    ```
 
+   Without the variable, a server already on the port fails the run, so a server left behind by an earlier run never serves an old build to new tests.
+
 This saves 60-90 seconds per run. Keep the server running while iterating on tests.
 
 > **Tip:** If port 3000 is already in use, change the port in both the `e2e:server` script in `package.json` and the `port` option in `playwright.config.js`.

package/dist/proxy/createPageManager.js

@@ -13,7 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { getBlock } from '../core/locators.js';
-import { waitForReady, waitForPage } from '../core/navigation.js';
+import { createPageUrl, waitForReady, waitForPage } from '../core/navigation.js';
 import { getState, getBlockState, setState } from '../core/state.js';
 import { getRequestState, getRequestResponse } from '../core/requests.js';
 import { getApiState, getApiResponse } from '../core/api.js';
@@ -36,6 +36,18 @@ function createPageManager({ page, manifest, helperRegistry, mockManager, assert
     const { expectState, expectRequest, expectApi, expectUrl, expectUrlQuery } = assertions;
     let currentBlockMap = null;
     let currentPageId = null;
+    // A { pageId, pathParams, urlQuery } target gets the app's basePath and the page's path
+    // pattern from the manifest.
+    function withPagePath(target) {
+        if (type.isString(target)) {
+            return target;
+        }
+        return {
+            basePath: manifest.basePath,
+            path: manifest.paths?.[target.pageId],
+            ...target
+        };
+    }
     function ensurePageLoaded() {
         if (!currentBlockMap) {
             throw new Error('Call goto() before accessing blocks');
@@ -128,8 +140,8 @@ function createPageManager({ page, manifest, helperRegistry, mockManager, assert
             await setUserCookie(page, userObj);
         },
         // Navigation (control flow)
-        async goto (path) {
-            await page.goto(path);
+        async goto (target) {
+            await page.goto(createPageUrl(withPagePath(target)));
             await waitForReady(page);
             currentPageId = await page.evaluate(()=>window.lowdefy?.pageId);
             currentBlockMap = manifest.pages[currentPageId];
@@ -138,8 +150,8 @@ function createPageManager({ page, manifest, helperRegistry, mockManager, assert
                 throw new Error(`Page "${currentPageId}" not found in manifest. Available pages: ${available || '(none)'}`);
             }
         },
-        async waitForPage (path) {
-            await waitForPage(page, path);
+        async waitForPage (target) {
+            await waitForPage(page, withPagePath(target));
             currentPageId = await page.evaluate(()=>window.lowdefy?.pageId);
             currentBlockMap = manifest.pages[currentPageId];
         },