@chidchanun/bcp 0.2.13 → 0.2.14

package/docs/testing-platform.md

@@ -0,0 +1,602 @@
+# Testing Platform
+
+BCP `0.2.14` adds the server-only `bcp/testing` entrypoint for framework-native testing without forcing Jest, Vitest or another test runner.
+
+The APIs work with Node's built-in `node:test`, but they are assertion-runner neutral and can also be used from other test runners.
+
+## Import
+
+```ts
+import {
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+    runTestPageAction,
+    runTestPageGuards,
+    runTestPageLoader,
+} from "bcp/testing";
+```
+
+`bcp/testing` is server-only and must not be imported from browser/client bundles.
+
+## Request harness
+
+`createTestApp()` wraps a Request -> Response handler and provides request helpers, default headers and an in-memory cookie jar.
+
+```ts
+const app =
+    createTestApp({
+        handler:
+            async request => {
+                return Response.json({
+                    method:
+                        request.method,
+                });
+            },
+    });
+
+const response =
+    await app.get("/api/health");
+
+await expectResponse(response)
+    .status(200)
+    .json({
+        method: "GET",
+    });
+```
+
+Available request methods:
+
+```text
+request()
+get()
+post()
+put()
+patch()
+delete()
+```
+
+JSON request bodies can be sent with:
+
+```ts
+await app.post(
+    "/api/users",
+    {
+        json: {
+            name: "BCP",
+        },
+    }
+);
+```
+
+When a response contains `Set-Cookie`, the test app updates its cookie jar and sends those cookies on later requests.
+
+```ts
+app.setCookie(
+    "theme",
+    "dark"
+);
+
+app.cookies();
+app.clearCookie("theme");
+```
+
+Default headers can also be changed between requests with `setHeader()` / `deleteHeader()`. Call `app.reset()` to restore the initial headers and cookies.
+
+## API route handler testing
+
+`createRouteTestHandler()` turns a BCP-style route module into a Request -> Response handler.
+
+```ts
+const handler =
+    createRouteTestHandler({
+        GET() {
+            return {
+                ok: true,
+            };
+        },
+
+        async POST(request) {
+            return Response.json({
+                received:
+                    await request.json(),
+            });
+        },
+    });
+```
+
+Supported route method exports:
+
+```text
+GET
+POST
+PUT
+PATCH
+DELETE
+HEAD
+OPTIONS
+```
+
+Missing methods return `405 Method Not Allowed` with an `Allow` header.
+
+Non-Response route values are normalized for tests:
+
+```text
+object/array/value -> Response.json(value)
+string             -> text Response
+undefined/null     -> 204 Response
+```
+
+A custom route context can be supplied through `createRouteTestHandler(route, { context })`.
+
+## Page guard testing
+
+`runTestPageGuards()` calls the real `executePageGuardFunctions()` runtime.
+
+```ts
+const result =
+    await runTestPageGuards(
+        [
+            ({ params }) => ({
+                userId:
+                    params.userId,
+            }),
+            ({ guardData }) => ({
+                allowed:
+                    guardData.userId ===
+                    "42",
+            }),
+        ],
+        {
+            params: {
+                userId: "42",
+            },
+            url:
+                "/users/42?mode=edit",
+        }
+    );
+```
+
+Guard data is chained in the same order as production execution. A guard `Response` such as a redirect stops the chain and is returned in `result.response`.
+
+The helper accepts either guard functions directly or `PageGuardDefinition` objects when a specific label/file path is useful.
+
+## Page loader testing
+
+`runTestPageLoader()` calls the production `executePageLoaderFunction()` path and provides params, search params and guard data.
+
+```ts
+const result =
+    await runTestPageLoader(
+        async ({
+            params,
+            searchParams,
+            guardData,
+        }) => ({
+            id: params.id,
+            tab:
+                searchParams.get(
+                    "tab"
+                ),
+            role:
+                guardData.role,
+        }),
+        {
+            params: {
+                id: "7",
+            },
+            url:
+                "/users/7?tab=profile",
+            guardData: {
+                role: "admin",
+            },
+        }
+    );
+```
+
+The result is the actual `PageLoaderExecution`, including `loaderData`, `guardData`, `hasPageLoader`, `hasGuard` and a possible Response short-circuit.
+
+## Form action testing
+
+`runTestPageAction()` calls the real `executePageActionFunction()` runtime.
+
+```ts
+const result =
+    await runTestPageAction(
+        async (
+            formData,
+            context
+        ) => ({
+            name:
+                formData.get(
+                    "name"
+                ),
+            method:
+                context.method,
+            userId:
+                context.params.userId,
+        }),
+        {
+            actionName:
+                "updateUser",
+            method: "PATCH",
+            params: {
+                userId: "42",
+            },
+            fields: {
+                name: "BCP",
+                tag: [
+                    "framework",
+                    "testing",
+                ],
+            },
+        }
+    );
+```
+
+Use `fields` for simple form construction or provide an existing `FormData` through `formData`. Specifying both is rejected.
+
+`createTestFormData()` is also exported for repeated/multipart-like field setup:
+
+```ts
+const formData =
+    createTestFormData({
+        role: [
+            "admin",
+            "developer",
+        ],
+    });
+```
+
+Action method validation, JSON-safe action data validation and Response short-circuit behavior all come from the production Form Action runtime.
+
+## Response assertions
+
+`expectResponse()` provides lightweight assertions without coupling BCP to a test framework.
+
+```ts
+await expectResponse(response)
+    .status(200)
+    .header(
+        "content-type",
+        /application\/json/
+    )
+    .json({
+        ok: true,
+    });
+```
+
+Available assertions:
+
+```text
+status()
+header()
+text()
+json()
+jsonMatches()
+```
+
+`jsonMatches()` checks only the provided object keys.
+
+## Signed auth sessions
+
+`createTestAuthSession()` creates the same signed HS256 session token used by BCP Auth.
+
+```ts
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
+
+When an `AuthSessionStore` is provided, the helper also writes the matching server-side session record.
+
+Supported options include `sid`, session data, `expiresIn`, issuer, audience, custom cookie name, custom ID factory and `AuthSessionStore`.
+
+This allows auth/role/permission route tests to use real BCP session verification rather than a fake user header.
+
+## Rollback database tests
+
+Use `withTestTransaction()` to run a test inside a real BCP database transaction and force rollback after the callback succeeds.
+
+```ts
+const result =
+    await withTestTransaction(
+        db,
+        async tx => {
+            await tx.execute(
+                "INSERT INTO users (name) VALUES (?)",
+                ["Test User"]
+            );
+
+            return tx.query(
+                "SELECT * FROM users"
+            );
+        }
+    );
+```
+
+The callback result is returned to the test, but BCP deliberately throws an internal rollback signal before the transaction can commit. If the callback itself throws, the original error is preserved.
+
+This helper assumes the configured database adapter rolls back a transaction when its callback rejects, which is the BCP database adapter contract.
+
+## Middleware tests
+
+`runTestMiddleware()` executes the real Middleware System v2 onion pipeline.
+
+```ts
+const response =
+    await runTestMiddleware(
+        middlewareModule,
+        {
+            url:
+                "http://bcp.test/dashboard",
+        },
+        request =>
+            Response.json({
+                header:
+                    request.headers.get(
+                        "x-middleware"
+                    ),
+            })
+    );
+```
+
+This supports matcher logic, request/response headers, redirects, rewrites, middleware state and `await next()` behavior through the framework runtime.
+
+## Fake clock
+
+Use `createFakeClock()` when testing jobs, schedulers, workflows or other time-sensitive code.
+
+```ts
+const clock =
+    createFakeClock(1_000);
+
+clock.now();
+clock.advance(500);
+clock.set(10_000);
+clock.reset();
+```
+
+Pass `clock.now` to runtime options that accept a `now` function.
+
+## Deterministic IDs
+
+```ts
+const idFactory =
+    createSequenceIdFactory(
+        "job",
+        1
+    );
+
+idFactory(); // job-1
+idFactory(); // job-2
+```
+
+This is useful for exact event/job/run assertions.
+
+## Background job harness
+
+```ts
+const jobs =
+    createJobTestHarness(
+        queue
+    );
+
+await jobs.drain();
+
+await jobs.expectCount(
+    1,
+    {
+        name: "email.welcome",
+        state: "succeeded",
+    }
+);
+```
+
+Available helpers are `drain()`, `records()`, `count()` and `expectCount()`.
+
+`drain()` processes currently eligible jobs synchronously by calling the queue's real `processNext()` API until the queue is idle or `maxJobs` is reached. Delayed jobs remain pending until the queue clock reaches their `availableAt` value.
+
+## Workflow harness
+
+```ts
+const workflows =
+    createWorkflowTestHarness(
+        onboarding
+    );
+
+const run =
+    await workflows.startAndRun({
+        userId: 42,
+    });
+
+await workflows.expectState(
+    run.id,
+    "succeeded"
+);
+```
+
+`runUntilIdle()` continues a workflow until it becomes terminal or reaches a persisted waiting state. For delay-oriented tests, `forceWaiting: true` can resume waiting workflows immediately.
+
+## Transactional outbox harness
+
+```ts
+const events =
+    createOutboxTestHarness(
+        outboxStore,
+        dispatcher
+    );
+
+await events.dispatchUntilIdle();
+
+await events.expectState(
+    eventId,
+    "published"
+);
+```
+
+The harness uses the real `OutboxStore` and `OutboxDispatcher`; it does not bypass leases, retry logic or delivery state transitions.
+
+`dispatchUntilIdle()` stops when a batch publishes zero events, so retry-delayed failures are not artificially time-skipped.
+
+## Realtime test socket
+
+`createRealtimeTestSocket()` implements the provider-neutral `RealtimeSocket` contract entirely in memory.
+
+```ts
+const socket =
+    createRealtimeTestSocket();
+
+await realtime.attachSocket(
+    socket
+);
+
+await socket.receive({
+    type: "join",
+    channel: "orders:42",
+});
+```
+
+Inspect server-to-client messages with `socket.sent()` / `socket.messages()`. Simulate client close/error events with `closeFromClient()` and `fail()`.
+
+## Realtime harness
+
+```ts
+const realtimeTest =
+    createRealtimeTestHarness(
+        realtime
+    );
+
+const {
+    socket,
+    connection,
+} =
+    await realtimeTest.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
+
+const event =
+    realtimeTest.expectEvent(
+        socket,
+        "order.updated",
+        "orders:42"
+    );
+```
+
+The harness uses the actual `RealtimeHub`, channel membership and broker dispatch path.
+
+## SSE testing
+
+`readSseEvents()` reads structured events from a Server-Sent Events response.
+
+```ts
+const response =
+    realtime.sse(
+        "workflow:42"
+    );
+
+await realtime.broadcast(
+    "workflow:42",
+    "workflow.progress",
+    {
+        progress: 50,
+    }
+);
+
+const [event] =
+    await readSseEvents(
+        response,
+        {
+            limit: 1,
+            timeoutMs: 1_000,
+        }
+    );
+```
+
+SSE comments and retry frames are ignored; `data:` is JSON-decoded when possible.
+
+## Test runner neutrality
+
+BCP does not depend on Jest or Vitest.
+
+Recommended built-in setup:
+
+```ts
+import assert from "node:assert/strict";
+import {
+    test,
+} from "node:test";
+```
+
+All `bcp/testing` helpers can also be used from another runner.
+
+## Production boundary
+
+`bcp/testing` is intended for tests and development tooling. It is server-only and the BCP client-boundary validator rejects it from pages/client islands.
+
+Applications should avoid importing `bcp/testing` from production request modules unless the deployed code intentionally includes a test-only route or diagnostic surface.
+
+## 0.2.14 scope
+
+Included:
+
+```text
+Request/Response test app
+cookie jar and default headers
+API route module testing
+page guard harness
+page loader harness
+form action harness
+FormData helper
+response assertions
+real signed BCP auth sessions
+optional AuthSessionStore registration
+rollback transaction helper
+real middleware pipeline runner
+fake clock
+deterministic ID factory
+background job harness
+workflow harness
+outbox harness
+fake realtime socket
+realtime harness
+SSE reader
+compiled testing.mjs package runtime
+```
+
+Not included in this milestone:
+
+```text
+browser DOM testing
+Playwright wrapper
+React component renderer
+snapshot framework
+coverage runner
+Jest/Vitest dependency
+containerized database provisioning
+```
+
+Those can be layered on top without changing the base `bcp/testing` contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -82,6 +82,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/realtime.mjs"
     },
+    "./testing": {
+      "types": "./packages/client/src/testing.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/testing.mjs"
+    },
     "./observability": {
       "types": "./packages/client/src/observability.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -32,6 +32,7 @@ const SERVER_ONLY_IMPORTS =
         "bcp/workflow",
         "bcp/events",
         "bcp/realtime",
+        "bcp/testing",
         "bcp/observability",
     ]);