@chidchanun/bcp 0.2.13 → 0.2.14

package/docs/api-reference.md

@@ -10,7 +10,7 @@ Universal React application APIs.
 
 Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound`, loader/action/guard hooks and router/navigation APIs.
 
-Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md).
+Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/island`
 
@@ -54,7 +54,7 @@ Server-only Database Platform v2 APIs.
 
 Built-in SQL providers are MySQL, PostgreSQL and SQLite. `BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
 
-Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/auth`
 
@@ -62,7 +62,7 @@ Server-only authentication and authorization APIs.
 
 The default authentication mode remains stateless signed JWT-cookie authentication. Applications may opt into server-side session stores, revocation, logout-all, idle timeout, role/permission guards and resource-aware authorization policies.
 
-Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md).
+Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/jobs`
 
@@ -78,7 +78,7 @@ BCP does not install a Redis library and does not create the connection. Applica
 
 The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
 
-Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
+Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
 ## `bcp/workflow`
 
@@ -111,7 +111,7 @@ When an existing `BackgroundJobQueue` is supplied, workflow execution and delay
 
 `WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
 
-Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
+Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
 ## `bcp/events`
 
@@ -136,7 +136,7 @@ import {
 
 Delivery is at-least-once; consumers should use idempotency controls for non-repeatable side effects.
 
-Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
+Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
 ## `bcp/realtime`
 
@@ -168,47 +168,145 @@ import {
 } from "bcp/realtime";
 ```
 
-### Hub and channels
-
 `createRealtime()` creates a server-side hub. Connections can `join()`, `leave()`, `emit()`, `send()`, `touch()` and `disconnect()`.
 
-`hub.broadcast(channel, event, payload)` delivers through the configured broker and reaches connections that joined the channel.
+`RealtimeBroker` is the cross-hub pub/sub boundary and `RealtimePresenceStore` is the channel-presence boundary. Built-in memory implementations are intended for tests/single-process use; shared deployments can supply provider adapters.
 
-### Broker
+`RealtimeOptions.authenticate` can resolve identity from a Request/connection payload, while `authorizeChannel` runs before channel membership is accepted.
 
-`RealtimeBroker` is the cross-hub pub/sub boundary. The memory implementation is process-local; production multi-instance applications can provide a shared broker such as Redis Pub/Sub or NATS without changing the hub surface.
+BCP does not install a WebSocket provider. `RealtimeSocket` defines the minimal transport surface consumed by `hub.attachSocket()`.
 
-### Presence
+`hub.sse()` and `createRealtimeSseResponse()` expose Web-standard Server-Sent Events responses with abort, filtering, retry hint and keep-alive options.
 
-`RealtimePresenceStore` tracks per-channel connection presence. `hub.members(channel)` returns current presence records.
+Realtime delivery is transient. Use database/outbox/jobs/workflows for durable state and refetch durable state/history after reconnect when catch-up is required.
 
-The memory store is intended for tests/single-process use. Shared deployments should use a shared presence adapter.
+Related guides: [Realtime Platform](realtime-platform.md), [Authentication](authentication.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
-### Authentication and channel authorization
+## `bcp/testing`
 
-`RealtimeOptions.authenticate` can resolve application user identity from a `Request`/connection data. `getUserId` maps that identity into presence records.
+Server-only Testing Platform APIs added in `0.2.14`.
 
-`RealtimeOptions.authorizeChannel` runs before `join()` completes and can enforce private-room access.
+```ts
+import {
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createTestFormData,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    runTestPageAction,
+    runTestPageGuards,
+    runTestPageLoader,
+    withTestTransaction,
+    type CreateTestAuthSessionOptions,
+    type FakeClock,
+    type JobTestHarness,
+    type OutboxTestHarness,
+    type ParsedSseEvent,
+    type RealtimeTestConnection,
+    type RealtimeTestHarness,
+    type RealtimeTestSocket,
+    type TestApp,
+    type TestAppOptions,
+    type TestAuthSession,
+    type TestPageActionOptions,
+    type TestPageContextOptions,
+    type TestPageGuardOptions,
+    type TestRequestHandler,
+    type TestRequestOptions,
+    type TestResponseExpectation,
+    type TestRouteFunction,
+    type TestRouteHandlerOptions,
+    type TestRouteMethod,
+    type TestRouteModule,
+    type TestTransactionDatabase,
+    type WorkflowTestHarness,
+} from "bcp/testing";
+```
 
-### Socket adapter
+### Request application harness
 
-BCP does not install a WebSocket provider. `RealtimeSocket` defines the minimal `send`, `close`, `onMessage`, `onClose` and optional `onError` surface consumed by `hub.attachSocket()`.
+`createTestApp()` runs a Web-standard `Request -> Response` handler with convenience methods for GET/POST/PUT/PATCH/DELETE, JSON bodies, mutable default headers and an in-memory cookie jar that consumes `Set-Cookie` responses.
 
-The built-in JSON protocol accepts `join`, `leave`, `event` and `ping` messages. `ping` receives a `realtime.pong` event.
+### API route module testing
 
-### Server-Sent Events
+`createRouteTestHandler()` adapts BCP-style method exports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`) to a Request handler. Missing methods return 405 with an `Allow` header.
 
-`hub.sse(channel, options)` and `createRealtimeSseResponse()` return Web-standard streaming `Response` objects using `text/event-stream`.
+Return values are normalized for tests: Response is preserved, strings become text Responses, null/undefined become 204, and other values become JSON.
 
-Options include abort signal integration, event filtering, retry hints, keep-alive timing and response headers.
+### Page loader, guard and form action testing
 
-### Heartbeat
+`runTestPageGuards()` executes one or more guards through the production `executePageGuardFunctions()` path. Guard data is chained in order and redirect/other Response short-circuits are preserved.
 
-`hub.startHeartbeat()` sends `realtime.ping` messages and invokes stale connection cleanup. `hub.sweepStale()` is also public for deterministic infrastructure loops/tests.
+`runTestPageLoader()` invokes the production `executePageLoaderFunction()` path with test params, URL/search params and optional guard data. The returned value is the normal `PageLoaderExecution` contract.
 
-Realtime delivery is transient. Use database/outbox/jobs/workflows for durable state and refetch durable state/history after reconnect when catch-up is required.
+`runTestPageAction()` invokes the production `executePageActionFunction()` path, including action-name/method validation, guard data, FormData and Response/data handling.
+
+`createTestFormData()` creates a FormData object from string/Blob fields and supports repeated values.
+
+### Response assertions
+
+`expectResponse()` exposes lightweight runner-neutral assertions:
+
+```text
+status()
+header()
+text()
+json()
+jsonMatches()
+```
+
+BCP does not require Jest/Vitest assertion APIs.
+
+### Auth testing
+
+`createTestAuthSession()` uses the production `createSessionToken()` implementation, including HS256 signature, issuer/audience and expiration semantics. It can also register the matching server-side record in an `AuthSessionStore`.
+
+This allows route/auth tests to use a real BCP session cookie instead of introducing a test-only identity header.
+
+### Database rollback testing
+
+`withTestTransaction()` executes a callback in a real BCP database transaction and deliberately rejects the transaction with an internal rollback sentinel after the test callback succeeds. The callback result is returned to the test while the transaction is rolled back.
+
+Application callback errors remain unchanged and are not swallowed.
+
+### Middleware testing
+
+`runTestMiddleware()` invokes the actual Middleware System v2 onion pipeline through `executeMiddlewarePipeline()` and supports a custom downstream Request handler.
+
+### Deterministic utilities
+
+`createFakeClock()` exposes `now()`, `set()`, `advance()` and `reset()` for time-sensitive queues/workflows/schedulers.
+
+`createSequenceIdFactory()` creates deterministic IDs for stable assertions.
+
+### Infrastructure harnesses
+
+`createJobTestHarness()` drains currently eligible work through the real `BackgroundJobQueue.processNext()` API and exposes record/count assertions.
+
+`createWorkflowTestHarness()` can start/run workflows until terminal or waiting state and optionally force persisted delays to resume.
+
+`createOutboxTestHarness()` dispatches through the actual `OutboxDispatcher` and exposes event/state/statistics helpers.
+
+`createRealtimeTestSocket()` implements the `RealtimeSocket` adapter contract entirely in memory. `createRealtimeTestHarness()` connects that socket to a real `RealtimeHub` and can assert server-sent channel events.
+
+`readSseEvents()` reads event-stream Responses, ignores comment/retry frames and JSON-decodes `data:` payloads when possible.
+
+### Runner neutrality and boundary
+
+`bcp/testing` has no dependency on Jest or Vitest. BCP's own suite uses Node `node:test`, but the helpers can be called from another runner.
+
+The package is server-only; the client boundary validator rejects `bcp/testing` from pages/client islands.
 
-Related guides: [Realtime Platform](realtime-platform.md), [Authentication](authentication.md), [Observability Platform v2](observability.md).
+Related guides: [Testing Platform](testing-platform.md), [Authentication](authentication.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Workflow Orchestration](workflow-orchestration.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md).
 
 ## `bcp/observability`
 
@@ -220,7 +318,7 @@ Related guides: [Observability Platform v2](observability.md), [Logging](develop
 
 Server request/runtime APIs including request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
 
-Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
+Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/server-only`
 
@@ -236,7 +334,7 @@ Related guide: [Application Modules](application-modules.md).
 
 Middleware System v2 APIs and types.
 
-Related guide: [Middleware](middleware.md).
+Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md).
 
 ## Stability
 

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.13",
+  "versionTarget": "0.2.14",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -88,10 +88,11 @@
     {
       "id": "developer-experience",
       "title": "Developer Experience",
-      "description": "Project generators, diagnostics, project metadata and framework maintenance tooling.",
+      "description": "Project generators, diagnostics, testing, project metadata and framework maintenance tooling.",
       "pages": [
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
-        { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" }
+        { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" },
+        { "route": "/docs/testing-platform", "source": "testing-platform.md", "title": "Testing Platform" }
       ]
     },
     {
@@ -114,7 +115,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13", "state": "unreleased" },
+    { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14", "state": "unreleased" },
+    { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13" },
     { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12" },
     { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11" },
     { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "releaseState": "unreleased",
-  "baseline": "realtime-platform",
+  "baseline": "testing-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -23,6 +23,7 @@
     "bcp/workflow",
     "bcp/events",
     "bcp/realtime",
+    "bcp/testing",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -121,6 +122,22 @@
     "realtimeServerSentEvents": true,
     "realtimeHeartbeats": true,
     "realtimeCrossHubBroadcast": true,
+    "testingPlatform": true,
+    "testRequestHarness": true,
+    "testRouteHandlers": true,
+    "testPageLoaders": true,
+    "testPageGuards": true,
+    "testFormActions": true,
+    "testResponseAssertions": true,
+    "testAuthSessions": true,
+    "testTransactionRollback": true,
+    "testMiddlewarePipeline": true,
+    "testJobHarness": true,
+    "testWorkflowHarness": true,
+    "testOutboxHarness": true,
+    "testRealtimeSocket": true,
+    "testSseReader": true,
+    "deterministicTestClock": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -160,7 +177,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.12",
+    "previousBaseline": "0.2.13",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -183,7 +200,8 @@
     "workflowOrchestration": "workflow-orchestration.md",
     "transactionalOutboxEvents": "transactional-outbox-events.md",
     "realtimePlatform": "realtime-platform.md",
+    "testingPlatform": "testing-platform.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.13.md"
+    "releaseNotes": "releases/0.2.14.md"
   }
 }

package/docs/releases/0.2.14.md

@@ -0,0 +1,241 @@
+# BCP Framework 0.2.14 — Testing Platform
+
+**Release state:** unreleased
+
+BCP `0.2.14` adds framework-native server-side testing utilities through the new `bcp/testing` entrypoint.
+
+The milestone is intentionally test-runner neutral: BCP does not add Jest or Vitest as runtime dependencies. The framework's own suite continues to use Node's built-in `node:test`.
+
+## Highlights
+
+- new server-only `bcp/testing` entrypoint,
+- Request -> Response application test harness,
+- persistent test cookie jar and default headers,
+- API route module testing for GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS,
+- page guard testing through the production guard executor,
+- page loader testing through the production loader executor,
+- form action testing through the production action executor,
+- `FormData` construction helper,
+- lightweight response assertions,
+- real signed BCP auth session generation,
+- optional `AuthSessionStore` registration,
+- rollback-only database test transactions,
+- real Middleware System v2 pipeline execution,
+- deterministic fake clock,
+- deterministic sequence ID factory,
+- background job queue drain/count helpers,
+- workflow execution/state helpers,
+- transactional outbox dispatch/state helpers,
+- in-memory `RealtimeSocket` test adapter,
+- realtime connection/event harness,
+- Server-Sent Events reader,
+- prepared package compilation to `testing.mjs`,
+- package smoke and client-boundary validation.
+
+## Public API
+
+```ts
+import {
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createTestFormData,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    runTestPageAction,
+    runTestPageGuards,
+    runTestPageLoader,
+    withTestTransaction,
+} from "bcp/testing";
+```
+
+## Request and route testing
+
+```ts
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
+
+const response =
+    await app.get(
+        "/api/health"
+    );
+
+await expectResponse(response)
+    .status(200)
+    .json({
+        ok: true,
+    });
+```
+
+The harness maintains cookies returned by `Set-Cookie` and sends them on future requests.
+
+## Page server runtime testing
+
+Page loader, guard and form action helpers invoke the same execution functions used by BCP runtime:
+
+```ts
+await runTestPageGuards(
+    guard,
+    {
+        params: {
+            id: "42",
+        },
+    }
+);
+
+await runTestPageLoader(
+    loader,
+    {
+        url:
+            "/users/42?tab=profile",
+    }
+);
+
+await runTestPageAction(
+    updateUser,
+    {
+        actionName:
+            "updateUser",
+        method: "PATCH",
+        fields: {
+            name: "BCP",
+        },
+    }
+);
+```
+
+This preserves guard-data chaining, loader/action Response short-circuits, action method validation and JSON-safe result validation.
+
+## Authentication testing
+
+`createTestAuthSession()` uses the same BCP session token implementation as production auth.
+
+```ts
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+        },
+        {
+            secret,
+            store:
+                authSessionStore,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
+
+This avoids introducing a framework-only fake user header.
+
+## Database rollback tests
+
+```ts
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+
+        // assertions
+    }
+);
+```
+
+After the callback succeeds, BCP deliberately rejects the database transaction with an internal rollback signal, then returns the callback result to the test.
+
+## Infrastructure harnesses
+
+`0.2.14` adds thin harnesses over the real platform contracts instead of separate mock implementations:
+
+```text
+BackgroundJobQueue       -> createJobTestHarness()
+Workflow                 -> createWorkflowTestHarness()
+OutboxStore + Dispatcher -> createOutboxTestHarness()
+RealtimeHub              -> createRealtimeTestHarness()
+RealtimeSocket           -> createRealtimeTestSocket()
+```
+
+## SSE
+
+```ts
+const events =
+    await readSseEvents(
+        response,
+        {
+            limit: 1,
+            timeoutMs: 1_000,
+        }
+    );
+```
+
+SSE comments and retry frames are ignored and JSON `data:` payloads are decoded when possible.
+
+## Package/runtime contract
+
+The prepared npm package now exposes:
+
+```text
+bcp/testing
+  types   -> packages/client/src/testing.ts
+  browser -> packages/client/src/server-only.browser.mjs
+  default -> packages/client/src/testing.mjs
+```
+
+`testing.mjs` is compiled during `package:prepare` so Node does not need a TypeScript loader to use the testing entrypoint from an installed package.
+
+## Compatibility
+
+`0.2.14` has no intentional breaking changes from `0.2.13`.
+
+All existing runtime entrypoints remain supported.
+
+## Validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The release must not be tagged or published until the final release commit passes the complete RC sequence.
+
+## Non-goals
+
+`0.2.14` does not add:
+
+- a DOM/browser renderer,
+- Playwright integration,
+- component snapshots,
+- a coverage runner,
+- a Jest dependency,
+- a Vitest dependency,
+- automatic Docker/database test provisioning.
+
+These can be layered on top of the base testing contracts in later milestones.