@chidchanun/bcp 0.2.13 → 0.2.14

package/README.md

@@ -1,10 +1,10 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, observability, uploads, storage and standalone Node.js deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.13 — Realtime Platform`
+> **Development target:** `0.2.14 — Testing Platform`
 >
-> `0.2.13` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.14` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -25,6 +25,7 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
 | Events | Transactional outbox, SQL persistence, dispatcher leases, retries, event bus and durable queue handoff |
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
+| Testing | Request/route/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
 | Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
 | Caching | Response cache and revalidation primitives |
@@ -73,6 +74,7 @@ import { createJobQueue } from "bcp/jobs";
 import { createWorkflow } from "bcp/workflow";
 import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
+import { createTestApp } from "bcp/testing";
 import { createMetricsRegistry } from "bcp/observability";
 ```
 
@@ -165,10 +167,6 @@ Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
 ## Realtime Platform — 0.2.13
 
-`0.2.13` adds the server-only `bcp/realtime` public entrypoint.
-
-Create a hub:
-
 ```ts
 import {
     createRealtime,
@@ -178,7 +176,7 @@ export const realtime =
     createRealtime();
 ```
 
-### Channels / rooms
+Join a channel and broadcast:
 
 ```ts
 const connection =
@@ -197,135 +195,179 @@ await realtime.broadcast(
 );
 ```
 
-Rooms are represented by channel names. Connections receive broadcasts only for channels they joined.
+BCP intentionally does not install a WebSocket server library. Applications adapt `ws`, uWebSockets.js or another transport to `RealtimeSocket`. SSE is built in through Web `Response`.
+
+Read more: [Realtime Platform](docs/realtime-platform.md)
+
+## Testing Platform — 0.2.14
 
-### Presence
+`0.2.14` adds the server-only `bcp/testing` entrypoint. It is test-runner neutral and does not add Jest or Vitest as framework dependencies.
+
+### Request and route tests
 
 ```ts
-await connection.join(
-    "project:7",
-    {
-        presence: {
-            status: "online",
+import {
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const handler =
+    createRouteTestHandler({
+        GET() {
+            return {
+                ok: true,
+            };
         },
-    }
-);
-
-const members =
-    await realtime.members(
-        "project:7"
-    );
-```
+    });
 
-The built-in memory presence store is process-local. Multi-instance deployments should provide a shared `RealtimePresenceStore`.
+const app =
+    createTestApp({
+        handler,
+    });
 
-### Authentication and private channels
+const response =
+    await app.get(
+        "/api/health"
+    );
 
-```ts
-const realtime =
-    createRealtime({
-        authenticate:
-            async ({ request }) =>
-                request
-                    ? loadRealtimeUser(
-                        request
-                    )
-                    : null,
-
-        getUserId:
-            user => user.id,
-
-        authorizeChannel:
-            ({ connection, channel }) =>
-                !channel.startsWith(
-                    "private:"
-                ) ||
-                Boolean(
-                    connection.user
-                ),
+await expectResponse(response)
+    .status(200)
+    .json({
+        ok: true,
     });
 ```
 
-### WebSocket provider contract
+`createTestApp()` keeps an in-memory cookie jar, supports default headers and can send JSON bodies directly.
 
-BCP intentionally does not install `ws`, Socket.IO or another WebSocket server dependency.
+### Authentication tests
 
-Adapt the selected server/provider to `RealtimeSocket`, then attach it:
+Create a real signed BCP session token instead of a fake test-only user header:
 
 ```ts
-const connection =
-    await realtime.attachSocket(
-        socketAdapter,
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
         {
-            request,
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+            store:
+                authSessionStore,
         }
     );
-```
 
-The JSON socket protocol supports `join`, `leave`, `event` and `ping` messages.
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
 
-### Server-Sent Events
+When `store` is provided, the matching server-side auth session record is inserted as well.
 
-SSE is built in through Web `Response`:
+### Rollback database tests
 
 ```ts
-export function GET(
-    request: Request
-) {
-    return realtime.sse(
-        "workflow:42",
-        {
-            signal:
-                request.signal,
-        }
-    );
-}
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+
+        // assertions run here
+    }
+);
 ```
 
-### Cross-instance delivery
+The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
 
-`RealtimeBroker` is the provider-neutral pub/sub boundary. The built-in memory broker supports same-process hubs; production applications can implement shared Redis/NATS/etc. brokers without changing hub APIs.
+### Infrastructure harnesses
 
-```text
-Browser A -> App A ----\
-                       Shared Broker
-Browser B -> App B ----/
-          |             |
-          +---- Shared Presence Store
+```ts
+import {
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createWorkflowTestHarness,
+} from "bcp/testing";
 ```
 
-### Heartbeat
+These harnesses use the real platform contracts rather than separate mock implementations.
+
+Background jobs:
 
 ```ts
-const heartbeat =
-    realtime.startHeartbeat({
-        intervalMs: 20_000,
-    });
+const jobTest =
+    createJobTestHarness(
+        jobs
+    );
+
+await jobTest.drain();
 
-// shutdown
-await heartbeat.stop();
-await realtime.close();
+await jobTest.expectCount(
+    1,
+    {
+        name: "email.welcome",
+        state: "succeeded",
+    }
+);
 ```
 
-`realtime.ping` / `realtime.pong` and `sweepStale()` provide connection liveness cleanup.
+Realtime:
 
-### Jobs / workflows / events integration
+```ts
+const realtimeTest =
+    createRealtimeTestHarness(
+        realtime
+    );
 
-Realtime is the transient delivery edge for durable backend state:
+const {
+    socket,
+    connection,
+} =
+    await realtimeTest.connect();
+
+await connection.join(
+    "orders:42"
+);
 
-```ts
 await realtime.broadcast(
-    `jobs:${job.id}`,
-    "job.progress",
+    "orders:42",
+    "order.updated",
     {
-        progress: 60,
+        status: "paid",
     }
 );
+
+realtimeTest.expectEvent(
+    socket,
+    "order.updated",
+    "orders:42"
+);
 ```
 
-Important business facts should remain in database/outbox/jobs/workflows. Realtime delivery is transient, so reconnecting clients should refetch durable state/history when catch-up is required.
+Other testing primitives include:
 
-Read more: [Realtime Platform](docs/realtime-platform.md)
+```text
+createFakeClock()
+createSequenceIdFactory()
+runTestMiddleware()
+createRealtimeTestSocket()
+readSseEvents()
+```
+
+Read more: [Testing Platform](docs/testing-platform.md)
 
 ## Public entrypoints
 
@@ -342,6 +384,7 @@ bcp/jobs
 bcp/workflow
 bcp/events
 bcp/realtime
+bcp/testing
 bcp/observability
 bcp/server
 bcp/server-only
@@ -397,6 +440,8 @@ Browser / API / Realtime clients
  outbox       jobs       |
     \__________|_________/
            durable state
+
+Testing Platform exercises these server contracts without becoming part of browser runtime.
 ```
 
 ## Packaging
@@ -424,7 +469,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.13`:
+Before publishing `0.2.14`:
 
 ```bash
 npm run typecheck
@@ -435,7 +480,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.13` adds unit and prepared-package smoke coverage for broker broadcasts, channel membership, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, public runtime compilation and browser boundary enforcement.
+`0.2.14` adds unit and prepared-package smoke coverage for request/route handling, cookies, signed auth sessions, rollback transactions, middleware execution, jobs, workflows, outbox delivery, realtime sockets, SSE parsing, public runtime compilation and browser boundary enforcement.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -463,12 +508,13 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
 
 ## Roadmap
 
-`0.2.13` establishes provider-neutral live delivery on top of the durable database/outbox/jobs/workflow stack.
+`0.2.14` establishes framework-native testing for the current BCP application/runtime stack without coupling the framework to a specific test runner.
 
-The next logical milestone is **`0.2.14 — Testing Platform`**, focused on framework-native request/route/auth/database/jobs/workflow/realtime testing utilities and application test harnesses.
+The next logical milestone is **`0.2.15 — Plugin & Module Platform`**, focused on reusable framework modules, lifecycle hooks, configuration extension, package metadata and plugin discovery/registration while keeping the current public entrypoints stable.
 
 Native desktop/mobile compilation remains later roadmap work.
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.13 — Realtime Platform`
+> **Documentation target:** BCP Framework `0.2.14 — Testing Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -39,56 +39,64 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
 
-## 0.2.13 — Realtime Platform
+## 0.2.14 — Testing Platform
 
-`0.2.13` adds the server-only `bcp/realtime` public entrypoint.
+`0.2.14` adds the server-only `bcp/testing` public entrypoint.
 
 Primary APIs:
 
 ```ts
 import {
-    createMemoryRealtimeBroker,
-    createMemoryRealtimePresenceStore,
-    createRealtime,
-    createRealtimeSseResponse,
-} from "bcp/realtime";
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    withTestTransaction,
+} from "bcp/testing";
 ```
 
-Runtime model:
+Testing model:
 
 ```text
-client connection
-      |
-      v
-RealtimeHub
-      |
-      +-- channels / rooms
-      +-- auth / channel authorization
-      +-- presence
-      +-- heartbeat
-      |
-      +-- RealtimeBroker
-      |       -> cross-hub delivery
-      |
-      +-- RealtimeSocket
-      |       -> WebSocket provider adapter
-      |
-      +-- SSE Response
+node:test / Vitest / Jest / other runner
+                |
+                v
+            bcp/testing
+                |
+     +----------+-----------+
+     |          |           |
+ Request     Database   Infrastructure
+ Route       rollback   jobs/workflow
+ Response      tx       outbox/realtime
+ Auth                    SSE/socket
+ Middleware
 ```
 
-The memory broker/presence store are process-local. Multi-instance deployments should provide shared implementations.
+The helpers use existing BCP runtime contracts rather than defining a parallel mock framework. Signed auth sessions use the production session token implementation; middleware tests execute the real onion pipeline; job/workflow/outbox/realtime harnesses wrap their actual platform APIs.
+
+BCP does not add a Jest or Vitest dependency.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `realtime-platform.md` | Channels, presence, WebSocket adapter, SSE, heartbeat and broker model |
-| `api-reference.md` | `bcp/realtime` public APIs |
-| `platform-manifest.json` | Realtime capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/realtime` source/guide ownership |
-| `docs-web-manifest.json` | Realtime docs navigation and `0.2.13` release route |
-| `releases/0.2.13.md` | Realtime Platform release notes |
+| `testing-platform.md` | Request, auth, database, middleware, jobs, workflow, outbox, realtime and SSE testing |
+| `api-reference.md` | `bcp/testing` public APIs |
+| `platform-manifest.json` | Testing capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/testing` source/guide ownership |
+| `docs-web-manifest.json` | Testing docs navigation and `0.2.14` release route |
+| `releases/0.2.14.md` | Testing Platform release notes |
 
 ## Update rule
 
@@ -114,8 +122,9 @@ When framework behavior or public surface changes:
 | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
 | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
 | `/docs/realtime-platform` | `realtime-platform.md` |
+| `/docs/testing-platform` | `testing-platform.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.13` | `releases/0.2.13.md` |
+| `/releases/0.2.14` | `releases/0.2.14.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -134,6 +143,7 @@ bcp/jobs
 bcp/workflow
 bcp/events
 bcp/realtime
+bcp/testing
 bcp/observability
 bcp/server
 bcp/server-only
@@ -144,7 +154,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.13`:
+Before publishing `0.2.14`:
 
 ```bash
 npm run typecheck
@@ -155,6 +165,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Realtime validation covers broker broadcasts, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, server-only boundaries, compiled `realtime.mjs` package execution and docs/platform/API parity.
+Testing Platform validation covers request/route behavior, cookie persistence, signed auth sessions, rollback transactions, middleware execution, deterministic clocks/IDs, job/workflow/outbox/realtime harnesses, SSE parsing, server-only boundaries, compiled `testing.mjs` execution and docs/platform/API parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -11,7 +11,7 @@
       "environment": "universal",
       "route": "/docs/api-reference#bcp",
       "summary": "React application APIs for routing, links, forms, loader/guard data, islands, metadata and route error handling.",
-      "guides": ["/docs/routing", "/docs/server-data-loaders", "/docs/route-guards", "/docs/form-actions"]
+      "guides": ["/docs/routing", "/docs/server-data-loaders", "/docs/route-guards", "/docs/form-actions", "/docs/testing-platform"]
     },
     {
       "package": "bcp/island",
@@ -59,7 +59,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
       "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
-      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events"]
+      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform"]
     },
     {
       "package": "bcp/auth",
@@ -67,7 +67,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
       "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards.",
-      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth"]
+      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform"]
     },
     {
       "package": "bcp/jobs",
@@ -75,7 +75,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-jobs",
       "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
-      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability"]
+      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability"]
     },
     {
       "package": "bcp/workflow",
@@ -83,7 +83,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-workflow",
       "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
-      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/observability"]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability"]
     },
     {
       "package": "bcp/events",
@@ -91,7 +91,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-events",
       "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
-      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/observability"]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability"]
     },
     {
       "package": "bcp/realtime",
@@ -99,7 +99,15 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-realtime",
       "summary": "Realtime channels, cross-hub broker delivery, presence, channel authorization, WebSocket adapter integration, heartbeat handling and built-in Server-Sent Events responses.",
-      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/observability"]
+      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability"]
+    },
+    {
+      "package": "bcp/testing",
+      "source": "packages/client/src/testing.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-testing",
+      "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
+      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform"]
     },
     {
       "package": "bcp/observability",
@@ -115,7 +123,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-server",
       "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs.",
-      "guides": ["/docs/server-request-apis", "/docs/authorization-security", "/docs/file-upload", "/docs/storage", "/docs/storage-ecosystem", "/docs/production-hardening"]
+      "guides": ["/docs/server-request-apis", "/docs/authorization-security", "/docs/file-upload", "/docs/storage", "/docs/storage-ecosystem", "/docs/production-hardening", "/docs/testing-platform"]
     },
     {
       "package": "bcp/server-only",
@@ -131,7 +139,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-middleware",
       "summary": "Middleware System v2 request/response pipeline types and helpers.",
-      "guides": ["/docs/middleware"]
+      "guides": ["/docs/middleware", "/docs/testing-platform"]
     }
   ]
 }