@theaiplatform/miniapp-sdk 0.3.0 → 0.3.1

package/README.md

@@ -1,16 +1,16 @@
 # The AI Platform Miniapp SDK
 
-`@theaiplatform/miniapp-sdk` is the public package for building portable
-miniapps that run in The AI Platform.
+`@theaiplatform/miniapp-sdk` is the TypeScript SDK for building, testing, and
+shipping portable miniapps on The AI Platform.
 
 ```bash
 pnpm add @theaiplatform/miniapp-sdk
 ```
 
 The package provides the host-injected SDK API, isolated surface lifecycle
-types, browser helpers, portable React UI components, manifest schema, and the
-Rspack/Rslib integration used to produce descriptor-backed Module Federation
-targets.
+types, browser helpers, portable React UI components, manifest schema,
+Rstest/Playwright integration, and the Rspack/Rslib integration used to produce
+descriptor-backed Module Federation targets.
 
 Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniapps/).
 
@@ -27,8 +27,28 @@ Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniap
 - `@theaiplatform/miniapp-sdk/surface`
 - `@theaiplatform/miniapp-sdk/config`
 - `@theaiplatform/miniapp-sdk/rspack`
+- `@theaiplatform/miniapp-sdk/testing/rstest`
 - `@theaiplatform/miniapp-sdk/config-schema.json`
 
+## In-app E2E testing in 0.3.1
+
+The `/testing/rstest` entry point extends Rstest's Playwright fixtures with a
+host-provided miniapp surface and exact TAP session provenance. Tests can assert
+both the rendered UI and the package/surface identity selected by the Test Lab:
+
+```ts
+import { expect, test } from '@theaiplatform/miniapp-sdk/testing/rstest';
+
+test('mounts the miniapp surface', async ({ surface, tap }) => {
+  await expect(surface.locator('body')).toBeVisible();
+  expect(tap.packageId).toBe('tap_pkg_example_0001');
+  expect(tap.surfaceId).toBe('example-surface');
+});
+```
+
+Install `@rstest/core@0.11.3`, `@rstest/playwright@0.11.3`, and Playwright as
+development dependencies when using this optional entry point.
+
 The host API is injected at runtime. Importing an entry point is safe in build
 tools and tests; host-backed calls fail when used outside a supported runtime.
 `sdk.storage` provides revisioned non-secret JSON scoped by the host to the

package/dist/testing/rstest.d.ts

@@ -0,0 +1,131 @@
+import { afterAll } from '@rstest/playwright';
+import { afterEach } from '@rstest/playwright';
+import { APIRequestContext } from 'playwright';
+import { beforeAll } from '@rstest/playwright';
+import { beforeEach } from '@rstest/playwright';
+import type { Browser } from 'playwright';
+import type { BrowserContext } from 'playwright';
+import { describe } from '@rstest/playwright';
+import { expect } from '@rstest/playwright';
+import type { FrameLocator } from 'playwright';
+import type { Page } from 'playwright';
+import { PlaywrightOptions } from '@rstest/playwright';
+import { PlaywrightServe } from '@rstest/playwright';
+import { PlaywrightTest } from '@rstest/playwright';
+import { z } from 'zod';
+
+export { afterAll }
+
+export { afterEach }
+
+export { beforeAll }
+
+export { beforeEach }
+
+export { describe }
+
+export { expect }
+
+/** Validate a driver session before any endpoint or provenance field is used. */
+export declare function parseTapMiniappTestSession(value: unknown): TapMiniappTestSession;
+
+declare const sessionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    workspaceId: z.ZodString;
+    channelId: z.ZodString;
+    packageId: z.ZodString;
+    installationId: z.ZodString;
+    mode: z.ZodEnum<{
+        surface: "surface";
+        "live-tap": "live-tap";
+    }>;
+    dataScope: z.ZodEnum<{
+        fixture: "fixture";
+        "selected-channel": "selected-channel";
+    }>;
+    permissionScenario: z.ZodString;
+    surfaceId: z.ZodString;
+    surfaceSelector: z.ZodString;
+    surfaceAssetOrigin: z.ZodString;
+    pageUrlPrefix: z.ZodString;
+    cdpEndpoint: z.ZodString;
+    cdpAuthorization: z.ZodString;
+    artifactDirectory: z.ZodString;
+    allowedNetworkOrigins: z.ZodArray<z.ZodString>;
+    credentialAliases: z.ZodArray<z.ZodString>;
+    releaseDigest: z.ZodOptional<z.ZodString>;
+    localGeneration: z.ZodOptional<z.ZodNumber>;
+    sourceDigest: z.ZodString;
+    testBundleDigest: z.ZodString;
+}, z.core.$strip>;
+
+export declare type TapMiniappTestControl = {
+    /** Restore the run's declared fixture and permission scenario. */
+    reset: () => Promise<void>;
+    /** Ask the TAP host to emit one versioned platform event through the normal frame bridge. */
+    emitHostEvent: (event: string, payload?: unknown) => Promise<void>;
+};
+
+export declare type TapMiniappTestFixture = Readonly<Pick<TapMiniappTestSession, 'channelId' | 'dataScope' | 'installationId' | 'localGeneration' | 'mode' | 'packageId' | 'permissionScenario' | 'releaseDigest' | 'runId' | 'sourceDigest' | 'surfaceId' | 'surfaceAssetOrigin' | 'testBundleDigest' | 'workspaceId'> & {
+    readonly allowedNetworkOrigins: readonly string[];
+    readonly credentialAliases: readonly string[];
+    control: TapMiniappTestControl;
+}>;
+
+export declare type TapMiniappTestSession = z.infer<typeof sessionSchema>;
+
+export declare type TapRstestFixtures = {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    /** Locator for the authorized miniapp iframe mounted by TAP's real frame host. */
+    surface: FrameLocator;
+    /** Provenance and scoped host controls for this exact test run. */
+    tap: TapMiniappTestFixture;
+};
+
+/**
+ * Rstest's Playwright test API with TAP-owned browser, page, iframe, and run
+ * fixtures. The upstream runner still owns scheduling, assertions, hooks, and
+ * reporting; TAP owns the privileged browser/session boundary.
+ */
+export declare const test: PlaywrightTest<    {
+browser: Browser;
+context: BrowserContext;
+request: APIRequestContext;
+surface: FrameLocator;
+page: Page;
+tap: Readonly<Pick<{
+schemaVersion: 1;
+runId: string;
+workspaceId: string;
+channelId: string;
+packageId: string;
+installationId: string;
+mode: "surface" | "live-tap";
+dataScope: "fixture" | "selected-channel";
+permissionScenario: string;
+surfaceId: string;
+surfaceSelector: string;
+surfaceAssetOrigin: string;
+pageUrlPrefix: string;
+cdpEndpoint: string;
+cdpAuthorization: string;
+artifactDirectory: string;
+allowedNetworkOrigins: string[];
+credentialAliases: string[];
+sourceDigest: string;
+testBundleDigest: string;
+releaseDigest?: string | undefined;
+localGeneration?: number | undefined;
+}, "packageId" | "installationId" | "workspaceId" | "channelId" | "mode" | "runId" | "dataScope" | "permissionScenario" | "surfaceId" | "surfaceAssetOrigin" | "releaseDigest" | "localGeneration" | "sourceDigest" | "testBundleDigest"> & {
+readonly allowedNetworkOrigins: readonly string[];
+readonly credentialAliases: readonly string[];
+control: TapMiniappTestControl;
+}>;
+playwright: PlaywrightOptions;
+serve: PlaywrightServe;
+}>;
+
+export { }

package/dist/testing/rstest.js

@@ -0,0 +1,241 @@
+import * as __rspack_external__rstest_playwright_5734ff29 from "@rstest/playwright";
+import * as __rspack_external_node_fs_promises_3b710708 from "node:fs/promises";
+import * as __rspack_external_node_path_806ed179 from "node:path";
+import * as __rspack_external_playwright from "playwright";
+import * as __rspack_external_zod from "zod";
+const SESSION_ENV = 'TAP_MINIAPP_TEST_SESSION_FILE';
+const sessionSchema = __rspack_external_zod.z.object({
+    schemaVersion: __rspack_external_zod.z.literal(1),
+    runId: __rspack_external_zod.z.string().min(1),
+    workspaceId: __rspack_external_zod.z.string().min(1),
+    channelId: __rspack_external_zod.z.string().min(1),
+    packageId: __rspack_external_zod.z.string().min(1),
+    installationId: __rspack_external_zod.z.string().min(1),
+    mode: __rspack_external_zod.z["enum"]([
+        'surface',
+        'live-tap'
+    ]),
+    dataScope: __rspack_external_zod.z["enum"]([
+        'fixture',
+        'selected-channel'
+    ]),
+    permissionScenario: __rspack_external_zod.z.string().min(1),
+    surfaceId: __rspack_external_zod.z.string().min(1),
+    surfaceSelector: __rspack_external_zod.z.string().min(1),
+    surfaceAssetOrigin: __rspack_external_zod.z.string().url(),
+    pageUrlPrefix: __rspack_external_zod.z.string().url(),
+    cdpEndpoint: __rspack_external_zod.z.string().url(),
+    cdpAuthorization: __rspack_external_zod.z.string().min(1),
+    artifactDirectory: __rspack_external_zod.z.string().min(1),
+    allowedNetworkOrigins: __rspack_external_zod.z.array(__rspack_external_zod.z.string().url()).max(128),
+    credentialAliases: __rspack_external_zod.z.array(__rspack_external_zod.z.string().min(1).max(256)).max(64),
+    releaseDigest: __rspack_external_zod.z.string().min(1).optional(),
+    localGeneration: __rspack_external_zod.z.number().int().nonnegative().optional(),
+    sourceDigest: __rspack_external_zod.z.string().min(1),
+    testBundleDigest: __rspack_external_zod.z.string().min(1)
+});
+let sessionPromise;
+let browserPromise;
+function parseTapMiniappTestSession(value) {
+    return sessionSchema.parse(value);
+}
+async function loadSession() {
+    sessionPromise ??= (async ()=>{
+        const sessionPath = process.env[SESSION_ENV]?.trim();
+        if (!sessionPath) throw new Error(`${SESSION_ENV} is missing. Start this suite from The AI Platform Miniapp Test Lab.`);
+        const raw = await (0, __rspack_external_node_fs_promises_3b710708.readFile)(sessionPath, 'utf8');
+        return parseTapMiniappTestSession(JSON.parse(raw));
+    })();
+    return sessionPromise;
+}
+function selectPage(context, session) {
+    const candidates = context.pages().filter((candidate)=>candidate.url().startsWith(session.pageUrlPrefix));
+    if (1 !== candidates.length) throw new Error(`TAP Browser Driver exposed ${candidates.length} matching pages for run ${session.runId}; expected exactly one.`);
+    const page = candidates[0];
+    if (!page) throw new Error('TAP Browser Driver page selection failed');
+    return page;
+}
+async function emitHostEvent(page, session, event, payload) {
+    if (!event.startsWith('tap.') || event.length > 160 || event.trim() !== event) throw new Error('TAP host events must be bounded, trimmed tap.* event names.');
+    await page.evaluate(({ controlEvent, event, payload, runId })=>{
+        const response = {};
+        globalThis.dispatchEvent(new CustomEvent(controlEvent, {
+            detail: {
+                event,
+                payload,
+                response,
+                runId
+            }
+        }));
+        if (response.error) throw new Error(response.error);
+        if (!response.delivered) throw new Error(`The TAP frame host has no active subscriber for ${event}. Declare the event on the miniapp surface before using it in a test.`);
+    }, {
+        controlEvent: 'tap:miniapp-test-control',
+        event,
+        payload,
+        runId: session.runId
+    });
+}
+function fixtureMetadata(session, page) {
+    return Object.freeze({
+        allowedNetworkOrigins: Object.freeze([
+            ...session.allowedNetworkOrigins
+        ]),
+        channelId: session.channelId,
+        credentialAliases: Object.freeze([
+            ...session.credentialAliases
+        ]),
+        control: Object.freeze({
+            emitHostEvent: (event, payload)=>emitHostEvent(page, session, event, payload),
+            reset: async ()=>{
+                await page.reload({
+                    waitUntil: 'domcontentloaded'
+                });
+                await page.locator(session.surfaceSelector).waitFor({
+                    state: 'attached'
+                });
+            }
+        }),
+        dataScope: session.dataScope,
+        installationId: session.installationId,
+        localGeneration: session.localGeneration,
+        mode: session.mode,
+        packageId: session.packageId,
+        permissionScenario: session.permissionScenario,
+        releaseDigest: session.releaseDigest,
+        runId: session.runId,
+        sourceDigest: session.sourceDigest,
+        surfaceAssetOrigin: session.surfaceAssetOrigin,
+        surfaceId: session.surfaceId,
+        testBundleDigest: session.testBundleDigest,
+        workspaceId: session.workspaceId
+    });
+}
+function safeArtifactSegment(value) {
+    return value.replaceAll(/[^a-zA-Z0-9._-]/g, '-').slice(0, 160);
+}
+const test = __rspack_external__rstest_playwright_5734ff29.test.extend({
+    browser: async (_context, use)=>{
+        const session = await loadSession();
+        browserPromise ??= __rspack_external_playwright.chromium.connectOverCDP(session.cdpEndpoint, {
+            headers: {
+                authorization: `Bearer ${session.cdpAuthorization}`,
+                'x-tap-miniapp-test-run': session.runId
+            }
+        });
+        await use(await browserPromise);
+    },
+    context: async ({ browser, task }, use)=>{
+        const session = await loadSession();
+        const contexts = browser.contexts().filter((candidate)=>candidate.pages().some((page)=>page.url().startsWith(session.pageUrlPrefix)));
+        if (1 !== contexts.length) throw new Error(`TAP Browser Driver exposed ${contexts.length} matching contexts for run ${session.runId}; expected exactly one.`);
+        const context = contexts[0];
+        if (!context) throw new Error('TAP Browser Driver context selection failed');
+        const hostPage = selectPage(context, session);
+        const runtimeOrigins = new Set(hostPage.frames().map((frame)=>originOf(frame.url())).filter((origin)=>void 0 !== origin));
+        const allowedOrigins = new Set([
+            ...runtimeOrigins,
+            new URL(session.surfaceAssetOrigin).origin,
+            ...session.allowedNetworkOrigins.map((value)=>new URL(value).origin)
+        ]);
+        const enforceNetworkPolicy = async (route)=>{
+            const url = route.request().url();
+            const origin = originOf(url);
+            if (void 0 === origin || allowedOrigins.has(origin)) return void await route.continue();
+            await route.abort('blockedbyclient');
+        };
+        await context.route('**/*', enforceNetworkPolicy);
+        const traceDirectory = (0, __rspack_external_node_path_806ed179.join)(session.artifactDirectory, 'traces', safeArtifactSegment(task.id));
+        await (0, __rspack_external_node_fs_promises_3b710708.mkdir)(traceDirectory, {
+            recursive: true
+        });
+        await context.tracing.start({
+            screenshots: true,
+            snapshots: true,
+            sources: true
+        });
+        try {
+            await use(context);
+        } finally{
+            await context.tracing.stop({
+                path: (0, __rspack_external_node_path_806ed179.join)(traceDirectory, 'trace.zip')
+            });
+            const traceSummary = {
+                schemaVersion: 1,
+                runId: session.runId,
+                taskId: task.id,
+                mode: session.mode,
+                dataScope: session.dataScope,
+                packageId: session.packageId,
+                surfaceId: session.surfaceId,
+                sourceDigest: session.sourceDigest,
+                testBundleDigest: session.testBundleDigest,
+                tracePath: 'trace.zip',
+                redactions: [
+                    'authorization headers',
+                    'cookies',
+                    'credential values',
+                    'network bodies'
+                ]
+            };
+            await Promise.all([
+                (0, __rspack_external_node_fs_promises_3b710708.writeFile)((0, __rspack_external_node_path_806ed179.join)(traceDirectory, 'trace-summary.json'), `${JSON.stringify(traceSummary, void 0, 2)}\n`, 'utf8'),
+                (0, __rspack_external_node_fs_promises_3b710708.writeFile)((0, __rspack_external_node_path_806ed179.join)(traceDirectory, 'debug.md'), [
+                    '# Miniapp test trace',
+                    '',
+                    `- Run: \`${session.runId}\``,
+                    `- Rstest task: \`${task.id}\``,
+                    `- Mode: \`${session.mode}\``,
+                    `- Data scope: \`${session.dataScope}\``,
+                    `- Surface: \`${session.surfaceId}\``,
+                    `- Source digest: \`${session.sourceDigest}\``,
+                    `- Test bundle digest: \`${session.testBundleDigest}\``,
+                    '',
+                    'Open `trace.zip` from The AI Platform Test Lab for the DOM, screenshots, console, and network timeline. The final assertion outcome is authoritative in `report.json` and `report.md`.',
+                    ''
+                ].join('\n'), 'utf8')
+            ]);
+            await context.unroute('**/*', enforceNetworkPolicy);
+        }
+    },
+    page: async ({ context }, use)=>{
+        const session = await loadSession();
+        const page = selectPage(context, session);
+        await page.locator(session.surfaceSelector).waitFor({
+            state: 'attached'
+        });
+        await use(page);
+    },
+    surface: async ({ page }, use)=>{
+        const session = await loadSession();
+        await use(page.frameLocator(session.surfaceSelector));
+    },
+    tap: async ({ page }, use)=>{
+        await use(fixtureMetadata(await loadSession(), page));
+    }
+});
+function originOf(value) {
+    try {
+        const url = new URL(value);
+        if (matchesNonNetworkScheme(url.protocol)) return;
+        return url.origin;
+    } catch  {
+        return;
+    }
+}
+function matchesNonNetworkScheme(protocol) {
+    return NON_NETWORK_PROTOCOLS.has(protocol);
+}
+const NON_NETWORK_PROTOCOLS = new Set([
+    'about:',
+    'blob:',
+    'data:',
+    'file:'
+]);
+var afterAll = __rspack_external__rstest_playwright_5734ff29.afterAll;
+var afterEach = __rspack_external__rstest_playwright_5734ff29.afterEach;
+var beforeAll = __rspack_external__rstest_playwright_5734ff29.beforeAll;
+var beforeEach = __rspack_external__rstest_playwright_5734ff29.beforeEach;
+var describe = __rspack_external__rstest_playwright_5734ff29.describe;
+var expect = __rspack_external__rstest_playwright_5734ff29.expect;
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, parseTapMiniappTestSession, test };

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@theaiplatform/miniapp-sdk",
-  "version": "0.3.0",
-  "description": "Public SDK for building portable miniapps that run in The AI Platform.",
+  "version": "0.3.1",
+  "description": "TypeScript SDK for building, testing, and shipping portable miniapps on The AI Platform.",
   "type": "module",
   "engines": {
     "node": ">=20"
   },
   "keywords": [
     "miniapp",
+    "playwright",
+    "react",
+    "rstest",
+    "tap",
+    "typescript",
     "module-federation",
     "rspack",
     "the-ai-platform"
@@ -54,7 +59,11 @@
       "types": "./dist/rspack/index.d.ts",
       "import": "./dist/rspack/index.js"
     },
-    "./config-schema.json": "./config-schema.json"
+    "./config-schema.json": "./config-schema.json",
+    "./testing/rstest": {
+      "types": "./dist/testing/rstest.d.ts",
+      "import": "./dist/testing/rstest.js"
+    }
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -119,7 +128,11 @@
         "types": "./dist/rspack/index.d.ts",
         "import": "./dist/rspack/index.js"
       },
-      "./config-schema.json": "./config-schema.json"
+      "./config-schema.json": "./config-schema.json",
+      "./testing/rstest": {
+        "types": "./dist/testing/rstest.d.ts",
+        "import": "./dist/testing/rstest.js"
+      }
     }
   },
   "peerDependencies": {
@@ -127,10 +140,13 @@
     "@module-federation/runtime-tools": "2.8.0",
     "@rsbuild/core": ">=2 <3",
     "@rslib/core": ">=0.21 <1",
+    "@rstest/core": "0.11.3",
+    "@rstest/playwright": "0.11.3",
     "@tanstack/react-query": ">=5 <6",
     "@tanstack/react-router": ">=1 <2",
     "react": ">=19 <20",
-    "react-dom": ">=19 <20"
+    "react-dom": ">=19 <20",
+    "playwright": ">=1.61 <2"
   },
   "peerDependenciesMeta": {
     "@module-federation/rsbuild-plugin": {
@@ -145,6 +161,12 @@
     "@rslib/core": {
       "optional": true
     },
+    "@rstest/core": {
+      "optional": true
+    },
+    "@rstest/playwright": {
+      "optional": true
+    },
     "@tanstack/react-query": {
       "optional": true
     },
@@ -156,6 +178,9 @@
     },
     "react-dom": {
       "optional": true
+    },
+    "playwright": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -165,6 +190,7 @@
     "@rsbuild/core": "^2.1.4",
     "@rslib/core": "^0.23.2",
     "@rstest/core": "catalog:rstest",
+    "@rstest/playwright": "catalog:rstest",
     "@tailwindcss/postcss": "^4.3.0",
     "@types/jsdom": "^28.0.3",
     "@types/node": "catalog:node",
@@ -172,6 +198,7 @@
     "@types/react-dom": "catalog:react",
     "jsdom": "^29.1.1",
     "postcss": "^8.5.6",
+    "playwright": "^1.61.0",
     "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
     "typescript": "catalog:typescript"