@testspectra/cli 1.0.70 → 1.1.0-rc.0

package/dist/types/generator.js

@@ -1,443 +1 @@
-import fs from "fs";
-import path from "path";
-const PLATFORM_HIERARCHY = {
-    web: ["web", "common"],
-    ios: ["ios", "mobile", "common", "web"],
-    android: ["android", "mobile", "common", "web"],
-    mobile: ["mobile", "common", "android", "ios", "web"],
-    common: ["common", "web", "mobile", "android", "ios"],
-};
-export class TypeGenerator {
-    /**
-     * Discovers all feature directories and shared library directories.
-     * Returns a map of scope -> base directory (e.g. { "shared": ".../shared/testing", "auth": ".../packages/features/auth/e2e" })
-     */
-    static getEntityScopes(cwd) {
-        const scopes = [];
-        // 1. Scan for shared directories
-        const sharedCandidates = [
-            path.join(cwd, "shared", "testing"),
-            path.join(cwd, "shared"),
-            path.join(cwd, "testing"),
-        ];
-        for (const cand of sharedCandidates) {
-            if (fs.existsSync(cand) &&
-                (fs.existsSync(path.join(cand, "page-objects")) ||
-                    fs.existsSync(path.join(cand, "support")) ||
-                    fs.existsSync(path.join(cand, "steps")) ||
-                    fs.existsSync(path.join(cand, "actions")) ||
-                    fs.existsSync(path.join(cand, "fixtures")))) {
-                if (!scopes.some((s) => s.dir === cand)) {
-                    scopes.push({ name: "shared", dir: cand, isShared: true });
-                }
-            }
-        }
-        // 2. Scan recursively for feature e2e directories
-        function scanForFeatures(dir, depth) {
-            if (depth <= 0 || !fs.existsSync(dir))
-                return;
-            const base = path.basename(dir);
-            if (base === "node_modules" || base === "dist" || base === ".git" || base === ".testspectra")
-                return;
-            if (base === "e2e" || base === "tests" || base === "specs") {
-                const featureDir = path.dirname(dir);
-                const featureName = path.basename(featureDir);
-                if (!scopes.some((s) => s.dir === dir)) {
-                    scopes.push({ name: featureName, dir: dir, isShared: false });
-                }
-                return;
-            }
-            try {
-                const entries = fs.readdirSync(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory()) {
-                        scanForFeatures(path.join(dir, entry.name), depth - 1);
-                    }
-                }
-            }
-            catch { }
-        }
-        scanForFeatures(cwd, 6);
-        return scopes;
-    }
-    static getPageObjectsDirsForScope(scopeDir, sharedDir) {
-        const dirs = [];
-        function scanDir(dir, maxDepth) {
-            if (maxDepth <= 0 || !fs.existsSync(dir))
-                return;
-            const base = path.basename(dir);
-            if (base === "node_modules" || base === "dist" || base === ".git" || base === ".testspectra")
-                return;
-            if (base === "page-objects" || base === "pageobjects") {
-                if (!dirs.includes(dir))
-                    dirs.push(dir);
-                return;
-            }
-            try {
-                const entries = fs.readdirSync(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory()) {
-                        scanDir(path.join(dir, entry.name), maxDepth - 1);
-                    }
-                }
-            }
-            catch { }
-        }
-        if (!sharedDir && (fs.existsSync(path.join(scopeDir, "pnpm-workspace.yaml")) || fs.existsSync(path.join(scopeDir, "nx.json")))) {
-            scanDir(scopeDir, 6);
-        }
-        else {
-            const candidates = [
-                path.join(scopeDir, "page-objects"),
-                path.join(scopeDir, "pageobjects"),
-            ];
-            if (sharedDir) {
-                candidates.push(path.join(sharedDir, "page-objects"));
-                candidates.push(path.join(sharedDir, "pageobjects"));
-            }
-            for (const c of candidates) {
-                if (fs.existsSync(c) && !dirs.includes(c))
-                    dirs.push(c);
-            }
-        }
-        return dirs;
-    }
-    static getEntityDirsForScope(entityType, scopeDir, sharedDir) {
-        const dirs = [];
-        function scanDir(dir, maxDepth) {
-            if (maxDepth <= 0 || !fs.existsSync(dir))
-                return;
-            const base = path.basename(dir);
-            if (base === "node_modules" || base === "dist" || base === ".git" || base === ".testspectra")
-                return;
-            if (base === entityType) {
-                if (!dirs.includes(dir))
-                    dirs.push(dir);
-                return;
-            }
-            try {
-                const entries = fs.readdirSync(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory()) {
-                        scanDir(path.join(dir, entry.name), maxDepth - 1);
-                    }
-                }
-            }
-            catch { }
-        }
-        if (!sharedDir && (fs.existsSync(path.join(scopeDir, "pnpm-workspace.yaml")) || fs.existsSync(path.join(scopeDir, "nx.json")))) {
-            scanDir(scopeDir, 6);
-        }
-        else {
-            const candidates = [
-                path.join(scopeDir, entityType),
-                path.join(scopeDir, "support", entityType),
-                path.join(scopeDir, "support", "testing", entityType),
-            ];
-            if (sharedDir) {
-                candidates.push(path.join(sharedDir, entityType));
-                candidates.push(path.join(sharedDir, "support", entityType));
-                candidates.push(path.join(sharedDir, "support", "testing", entityType));
-            }
-            for (const c of candidates) {
-                if (fs.existsSync(c) && !dirs.includes(c))
-                    dirs.push(c);
-            }
-        }
-        return dirs;
-    }
-    static generateDeclarationsForScope(cwd, outputTypesDir, scopeDir, sharedDir) {
-        const poDirs = this.getPageObjectsDirsForScope(scopeDir, sharedDir);
-        const actionsDirs = this.getEntityDirsForScope("actions", scopeDir, sharedDir);
-        const stepsDirs = this.getEntityDirsForScope("steps", scopeDir, sharedDir);
-        const platforms = ["web", "android", "ios", "mobile", "common"];
-        const results = {};
-        for (const platform of platforms) {
-            const hierarchy = PLATFORM_HIERARCHY[platform];
-            let content = `// Auto-generated ambient declarations for TestSpectra [${platform.toUpperCase()}]\n`;
-            content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
-            content += `/// <reference types="@wdio/globals/types" />\n`;
-            content += `/// <reference types="@wdio/mocha-framework" />\n`;
-            content += `/// <reference types="@testspectra/matchers" />\n`;
-            content += `/// <reference path="./fixtures.d.ts" />\n\n`;
-            // 1. Page Objects Global Declarations
-            const declaredPOMs = new Set();
-            for (const poDir of poDirs) {
-                if (!fs.existsSync(poDir))
-                    continue;
-                const poEntries = fs.readdirSync(poDir, { withFileTypes: true });
-                for (const entry of poEntries) {
-                    if (entry.name.startsWith("."))
-                        continue;
-                    if (entry.isDirectory()) {
-                        const className = entry.name;
-                        if (declaredPOMs.has(className))
-                            continue;
-                        const classFolder = path.join(poDir, className);
-                        let matchedFile = null;
-                        for (const stem of hierarchy) {
-                            const candidates = [
-                                path.join(classFolder, `${stem}.ts`),
-                                path.join(classFolder, `${stem}.page.ts`),
-                                path.join(classFolder, `${stem}.po.ts`),
-                                path.join(classFolder, "index.ts"),
-                                path.join(classFolder, "common.ts"),
-                            ];
-                            for (const cand of candidates) {
-                                if (fs.existsSync(cand)) {
-                                    matchedFile = path.relative(outputTypesDir, cand).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                                    if (!matchedFile.startsWith("."))
-                                        matchedFile = `./${matchedFile}`;
-                                    break;
-                                }
-                            }
-                            if (matchedFile)
-                                break;
-                        }
-                        if (matchedFile) {
-                            content += `declare const ${className}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            declaredPOMs.add(className);
-                        }
-                    }
-                    else if (entry.isFile() && entry.name.endsWith(".ts")) {
-                        const parts = entry.name.split(".");
-                        const className = parts[0];
-                        if (declaredPOMs.has(className))
-                            continue;
-                        let isMatch = false;
-                        if (parts.length === 2) {
-                            // E.g. ProfilePage.ts (applies to all platforms)
-                            isMatch = true;
-                        }
-                        else if (parts.length > 2) {
-                            // E.g. ProfilePage.web.ts or ProfilePage.android.ts
-                            const stem = parts[1];
-                            isMatch = hierarchy.includes(stem);
-                        }
-                        if (isMatch) {
-                            let rel = path.relative(outputTypesDir, path.join(poDir, entry.name)).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                            if (!rel.startsWith("."))
-                                rel = `./${rel}`;
-                            content += `declare const ${className}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            declaredPOMs.add(className);
-                        }
-                    }
-                }
-            }
-            // 2. Built-in Spectra Static Methods & Custom Actions
-            content += `interface TestSpectraCustomActions {\n`;
-            const declaredActions = new Set();
-            for (const actionsDir of actionsDirs) {
-                if (!fs.existsSync(actionsDir))
-                    continue;
-                const actionEntries = fs.readdirSync(actionsDir, { withFileTypes: true });
-                for (const entry of actionEntries) {
-                    if (entry.name.startsWith("."))
-                        continue;
-                    if (entry.isDirectory()) {
-                        const actionName = entry.name;
-                        if (declaredActions.has(actionName))
-                            continue;
-                        const actionFolder = path.join(actionsDir, actionName);
-                        let matchedFile = null;
-                        for (const stem of hierarchy) {
-                            const cand1 = path.join(actionFolder, `${stem}.action.ts`);
-                            const cand2 = path.join(actionFolder, `${stem}.ts`);
-                            if (fs.existsSync(cand1)) {
-                                matchedFile = path.relative(outputTypesDir, cand1).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                                break;
-                            }
-                            else if (fs.existsSync(cand2)) {
-                                matchedFile = path.relative(outputTypesDir, cand2).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                                break;
-                            }
-                        }
-                        if (matchedFile) {
-                            if (!matchedFile.startsWith("."))
-                                matchedFile = `./${matchedFile}`;
-                            const camel = actionName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
-                            content += `  "${actionName}": (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            if (camel !== actionName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
-                                content += `  ${camel}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            }
-                            declaredActions.add(actionName);
-                        }
-                    }
-                    else if (entry.isFile() && entry.name.endsWith(".ts")) {
-                        const parts = entry.name.split(".");
-                        const stem = parts.length > 2 ? parts[parts.length - 2] : parts[0];
-                        const actionName = parts[0];
-                        if (hierarchy.includes(stem) || hierarchy.includes(parts[1])) {
-                            if (declaredActions.has(actionName))
-                                continue;
-                            let rel = path.relative(outputTypesDir, path.join(actionsDir, entry.name)).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                            if (!rel.startsWith("."))
-                                rel = `./${rel}`;
-                            const camel = actionName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
-                            content += `  "${actionName}": (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            if (camel !== actionName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
-                                content += `  ${camel}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            }
-                            declaredActions.add(actionName);
-                        }
-                    }
-                }
-            }
-            content += `}\n`;
-            content += `type TestSpectraActions = import('@testspectra/matchers').SpectraStatic & TestSpectraCustomActions;\n`;
-            content += `declare const Spectra: TestSpectraActions;\n\n`;
-            // 3. Built-in Steps Declaration
-            content += `interface TestSpectraSteps {\n`;
-            const declaredSteps = new Set();
-            for (const stepsDir of stepsDirs) {
-                if (!fs.existsSync(stepsDir))
-                    continue;
-                const stepEntries = fs.readdirSync(stepsDir, { withFileTypes: true });
-                for (const entry of stepEntries) {
-                    if (entry.name.startsWith("."))
-                        continue;
-                    if (entry.isDirectory()) {
-                        const stepName = entry.name;
-                        if (declaredSteps.has(stepName))
-                            continue;
-                        const stepFolder = path.join(stepsDir, stepName);
-                        let matchedFile = null;
-                        for (const stem of hierarchy) {
-                            const cand1 = path.join(stepFolder, `${stem}.step.ts`);
-                            const cand2 = path.join(stepFolder, `${stem}.ts`);
-                            if (fs.existsSync(cand1)) {
-                                matchedFile = path.relative(outputTypesDir, cand1).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                                break;
-                            }
-                            else if (fs.existsSync(cand2)) {
-                                matchedFile = path.relative(outputTypesDir, cand2).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                                break;
-                            }
-                        }
-                        if (matchedFile) {
-                            if (!matchedFile.startsWith("."))
-                                matchedFile = `./${matchedFile}`;
-                            const camel = stepName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
-                            content += `  "${stepName}": (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            if (camel !== stepName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
-                                content += `  ${camel}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            }
-                            declaredSteps.add(stepName);
-                        }
-                    }
-                    else if (entry.isFile() && entry.name.endsWith(".ts")) {
-                        const parts = entry.name.split(".");
-                        const stem = parts.length > 2 ? parts[parts.length - 2] : parts[0];
-                        const stepName = parts[0];
-                        if (hierarchy.includes(stem) || hierarchy.includes(parts[1])) {
-                            if (declaredSteps.has(stepName))
-                                continue;
-                            let rel = path.relative(outputTypesDir, path.join(stepsDir, entry.name)).replace(/\\/g, "/").replace(/\.ts$/, ".js");
-                            if (!rel.startsWith("."))
-                                rel = `./${rel}`;
-                            const camel = stepName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
-                            content += `  "${stepName}": (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            if (camel !== stepName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
-                                content += `  ${camel}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            }
-                            declaredSteps.add(stepName);
-                        }
-                    }
-                }
-            }
-            content += `}\n`;
-            content += `declare const Step: TestSpectraSteps;\n\n`;
-            results[platform] = content;
-        }
-        return results;
-    }
-    static generateFixturesDeclarationForScope(cwd, outputTypesDir, scopeDir, sharedDir) {
-        const fixturesDirs = this.getEntityDirsForScope("fixtures", scopeDir, sharedDir);
-        let content = `// Auto-generated ambient fixture declarations for TestSpectra\n`;
-        content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
-        content += `interface TestSpectraFixtures {\n`;
-        const declaredFixtures = new Set();
-        function scanFixtureDir(dir) {
-            if (!fs.existsSync(dir))
-                return;
-            try {
-                const entries = fs.readdirSync(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.name.startsWith("."))
-                        continue;
-                    if (entry.isDirectory()) {
-                        scanFixtureDir(path.join(dir, entry.name));
-                    }
-                    else if (entry.isFile()) {
-                        const parsed = path.parse(entry.name);
-                        const varName = parsed.name.replace(/[^a-zA-Z0-9_$]/g, "_");
-                        if (declaredFixtures.has(varName))
-                            continue;
-                        if (entry.name.endsWith(".json")) {
-                            let rel = path.relative(outputTypesDir, path.join(dir, entry.name)).replace(/\\/g, "/");
-                            if (!rel.startsWith("."))
-                                rel = `./${rel}`;
-                            content += `  readonly ${varName}: typeof import('${rel}');\n`;
-                        }
-                        else {
-                            content += `  readonly ${varName}: string;\n`;
-                        }
-                        declaredFixtures.add(varName);
-                    }
-                }
-            }
-            catch { }
-        }
-        for (const fixturesDir of fixturesDirs) {
-            scanFixtureDir(fixturesDir);
-        }
-        content += `}\n`;
-        content += `declare const Fixture: TestSpectraFixtures;\n`;
-        return content;
-    }
-    static writeDeclarationFiles(cwd) {
-        const rootTypesDir = path.join(cwd, ".testspectra", "types");
-        if (!fs.existsSync(rootTypesDir)) {
-            fs.mkdirSync(rootTypesDir, { recursive: true });
-        }
-        const scopes = this.getEntityScopes(cwd);
-        const sharedScope = scopes.find((s) => s.isShared);
-        // 1. Generate Global / Standalone Root Types (or fallback)
-        const rootFixtures = this.generateFixturesDeclarationForScope(cwd, rootTypesDir, cwd);
-        fs.writeFileSync(path.join(rootTypesDir, "fixtures.d.ts"), rootFixtures, "utf-8");
-        const rootDeclarations = this.generateDeclarationsForScope(cwd, rootTypesDir, cwd);
-        for (const [platform, content] of Object.entries(rootDeclarations)) {
-            fs.writeFileSync(path.join(rootTypesDir, `${platform}.d.ts`), content, "utf-8");
-        }
-        // 2. Generate Scoped Types for Shared Library: .testspectra/types/shared/
-        if (sharedScope) {
-            const sharedTypesDir = path.join(rootTypesDir, "shared");
-            if (!fs.existsSync(sharedTypesDir))
-                fs.mkdirSync(sharedTypesDir, { recursive: true });
-            const sharedFixtures = this.generateFixturesDeclarationForScope(cwd, sharedTypesDir, sharedScope.dir);
-            fs.writeFileSync(path.join(sharedTypesDir, "fixtures.d.ts"), sharedFixtures, "utf-8");
-            // Shared scope has NO feature dependencies (only shared itself)
-            const sharedDeclarations = this.generateDeclarationsForScope(cwd, sharedTypesDir, sharedScope.dir);
-            for (const [platform, content] of Object.entries(sharedDeclarations)) {
-                fs.writeFileSync(path.join(sharedTypesDir, `${platform}.d.ts`), content, "utf-8");
-            }
-        }
-        // 3. Generate Scoped Types for Feature Modules: .testspectra/types/features/<featureName>/
-        const featureScopes = scopes.filter((s) => !s.isShared);
-        for (const feature of featureScopes) {
-            const featureTypesDir = path.join(rootTypesDir, "features", feature.name);
-            if (!fs.existsSync(featureTypesDir))
-                fs.mkdirSync(featureTypesDir, { recursive: true });
-            const featureFixtures = this.generateFixturesDeclarationForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir);
-            fs.writeFileSync(path.join(featureTypesDir, "fixtures.d.ts"), featureFixtures, "utf-8");
-            // Feature scope gets (feature + shared) ONLY
-            const featureDeclarations = this.generateDeclarationsForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir);
-            for (const [platform, content] of Object.entries(featureDeclarations)) {
-                fs.writeFileSync(path.join(featureTypesDir, `${platform}.d.ts`), content, "utf-8");
-            }
-        }
-        // Universal ambient index
-        const universalPath = path.join(rootTypesDir, "index.d.ts");
-        fs.writeFileSync(universalPath, `/// <reference path="./common.d.ts" />\n`, "utf-8");
-    }
-}
+export * from '../generator/type-generator.js';

package/dist/utils/__tests__/api-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/api-server.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { DemoApiServer } from '../api-server.js';
+describe('DemoApiServer self-hosted REST API (cli/src/utils/api-server.ts)', () => {
+    let server;
+    let port;
+    const base = () => `http://127.0.0.1:${port}`;
+    beforeAll(async () => {
+        server = new DemoApiServer(0);
+        const info = await server.start();
+        port = info.port;
+    });
+    afterAll(async () => {
+        await server?.stop();
+    });
+    it('GET /api/posts returns the self-hosted post list', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(Array.isArray(data)).toBe(true);
+        expect(data.length).toBeGreaterThan(0);
+        expect(data[0]).toHaveProperty('id');
+        expect(data[0]).toHaveProperty('title');
+    });
+    it('GET /api/users returns a user list with name/email', async () => {
+        const res = await fetch(`${base()}/api/users`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(Array.isArray(data)).toBe(true);
+        expect(data[0]).toHaveProperty('name');
+        expect(data[0]).toHaveProperty('email');
+    });
+    it('GET /api/todos/1 returns a single todo', async () => {
+        const res = await fetch(`${base()}/api/todos/1`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(data).toHaveProperty('id', 1);
+        expect(data).toHaveProperty('completed');
+    });
+    it('POST /api/posts creates a post with a numeric id (201)', async () => {
+        const res = await fetch(`${base()}/api/posts`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json; charset=UTF-8' },
+            body: JSON.stringify({ title: 'TestSpectra seeded post', body: 'Hook seeding', userId: 1 }),
+        });
+        expect(res.status).toBe(201);
+        const data = await res.json();
+        expect(typeof data.id).toBe('number');
+        expect(data.title).toBe('TestSpectra seeded post');
+    });
+    it('DELETE /api/posts/:id cleans up a seeded post (200)', async () => {
+        const res = await fetch(`${base()}/api/posts/123`, { method: 'DELETE' });
+        expect(res.status).toBe(200);
+    });
+    it('returns CORS headers on API responses', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        expect(res.headers.get('access-control-allow-origin')).toBe('*');
+    });
+    it('returns 404 for unknown API routes', async () => {
+        const res = await fetch(`${base()}/api/does-not-exist`);
+        expect(res.status).toBe(404);
+    });
+});

package/dist/utils/__tests__/demo-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/demo-server.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { DemoServer } from '../demo-server.js';
+describe('DemoServer static web app (cli/src/utils/demo-server.ts)', () => {
+    let server;
+    let port;
+    const demoDistAvailable = DemoServer.resolveDemoDist() !== null;
+    const base = () => `http://127.0.0.1:${port}`;
+    beforeAll(async () => {
+        if (!demoDistAvailable)
+            return;
+        server = new DemoServer(0);
+        const info = await server.start();
+        port = info.port;
+    });
+    afterAll(async () => {
+        await server?.stop();
+    });
+    it.skipIf(!demoDistAvailable)('serves the demo web app index', async () => {
+        const res = await fetch(`${base()}/`);
+        expect(res.status).toBe(200);
+        expect(await res.text()).toContain('<div id="app"></div>');
+    });
+    it.skipIf(!demoDistAvailable)('falls back to index.html for SPA routes', async () => {
+        const res = await fetch(`${base()}/some/spa/route`);
+        expect(res.status).toBe(200);
+        expect(await res.text()).toContain('<div id="app"></div>');
+    });
+    it.skipIf(!demoDistAvailable)('does not serve /api/* (that is the separate DemoApiServer)', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        // /api/posts is not a static file, so the SPA fallback serves index.html (200) — never JSON.
+        const text = await res.text();
+        expect(text).toContain('<div id="app"></div>');
+        expect(() => JSON.parse(text)).toThrow();
+    });
+});

package/dist/utils/api-server.d.ts

@@ -0,0 +1,19 @@
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+export declare const DEMO_API_PORT = 5200;
+/**
+ * Standalone self-hosted REST API server for the demo apps, kept separate from `DemoServer` (the
+ * static web app) so the API can run independently and either server can be swapped for a real
+ * backend in a project. Mirrors the small subset of jsonplaceholder.typicode.com shapes the demo's
+ * API sections exercise.
+ */
+export declare class DemoApiServer {
+    private server;
+    private port;
+    constructor(port?: number);
+    start(): Promise<{
+        url: string;
+        port: number;
+    }>;
+    private handleApi;
+    stop(): Promise<void>;
+}