@chidchanun/bcp 0.2.12 → 0.2.14

package/docs/README.md

@@ -2,14 +2,12 @@
 
 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.12 — Transactional Outbox & Events`
+> **Documentation target:** BCP Framework `0.2.14 — Testing Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
 ## Documentation architecture
 
-BCP uses three machine-readable contracts:
-
 ```text
 docs/docs-web-manifest.json
   -> website navigation, routes, Markdown sources and release routes
@@ -40,54 +38,65 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.10` | Durable Jobs Platform |
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
+| `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
 
-## 0.2.12 — Transactional Outbox & Events
+## 0.2.14 — Testing Platform
 
-`0.2.12` adds the server-only `bcp/events` public entrypoint.
+`0.2.14` adds the server-only `bcp/testing` public entrypoint.
 
 Primary APIs:
 
 ```ts
 import {
-    createEventBus,
-    createMemoryOutboxStore,
-    createOutboxDispatcher,
-    createOutboxMigrationSql,
-    createSqlOutboxStore,
-    createTransactionalOutbox,
-} from "bcp/events";
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    withTestTransaction,
+} from "bcp/testing";
 ```
 
-The central write model is:
+Testing model:
 
 ```text
-BCP Database transaction
-       |
-       +-- business data
-       +-- SQL outbox event
-       |
-     COMMIT
-       |
-       v
-Outbox Dispatcher
-       |
-       +-- bcp/jobs
-       +-- custom publisher
-       +-- local EventBus
+node:test / Vitest / Jest / other runner
+                |
+                v
+            bcp/testing
+                |
+     +----------+-----------+
+     |          |           |
+ Request     Database   Infrastructure
+ Route       rollback   jobs/workflow
+ Response      tx       outbox/realtime
+ Auth                    SSE/socket
+ Middleware
 ```
 
-`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite and writes the event using the caller-provided `TransactionDatabase`. The dispatcher adds leasing, stale recovery, retry/backoff and terminal failure handling after commit.
+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 documentation sources:
+New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `transactional-outbox-events.md` | Transactional publishing, SQL migration, dispatcher lifecycle and delivery guarantees |
-| `api-reference.md` | `bcp/events` public APIs |
-| `platform-manifest.json` | Events capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/events` source/guide ownership |
-| `docs-web-manifest.json` | Outbox docs navigation and `0.2.12` release route |
-| `releases/0.2.12.md` | Transactional Outbox & Events 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
 
@@ -107,16 +116,15 @@ When framework behavior or public surface changes:
 | Website route | Markdown source |
 | --- | --- |
 | `/docs/authentication` | `authentication.md` |
-| `/docs/authorization-security` | `authorization-security.md` |
 | `/docs/observability` | `observability.md` |
 | `/docs/background-jobs` | `background-jobs.md` |
-| `/docs/job-scheduling` | `job-scheduling.md` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
 | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
 | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
-| `/docs/database` | `database.md` |
+| `/docs/realtime-platform` | `realtime-platform.md` |
+| `/docs/testing-platform` | `testing-platform.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.12` | `releases/0.2.12.md` |
+| `/releases/0.2.14` | `releases/0.2.14.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -134,6 +142,8 @@ bcp/auth
 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.12`:
+Before publishing `0.2.14`:
 
 ```bash
 npm run typecheck
@@ -155,20 +165,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Transactional Outbox & Events validation covers:
-
-- transaction-bound SQL outbox insertion,
-- queue handoff,
-- custom/event-bus delivery,
-- retry and terminal failure,
-- dispatcher lease recovery,
-- MySQL/PostgreSQL/SQLite migration generation,
-- server-only browser boundary enforcement,
-- compiled `events.mjs` package execution,
-- docs/platform/API version 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.
-
-## Repository authority
-
-The framework repository remains authoritative for source, public exports, tests, Markdown docs, manifests and release notes. `bcp-docs-web` remains the presentation/search/navigation layer.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -11,12 +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",
@@ -24,9 +19,7 @@
       "environment": "universal",
       "route": "/docs/api-reference#bcp-island",
       "summary": "Partial-hydration island creation and island loading strategy types.",
-      "guides": [
-        "/docs/hydration"
-      ]
+      "guides": ["/docs/hydration"]
     },
     {
       "package": "bcp/cache",
@@ -34,9 +27,7 @@
       "environment": "server-preferred",
       "route": "/docs/api-reference#bcp-cache",
       "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
-      "guides": [
-        "/docs/caching"
-      ]
+      "guides": ["/docs/caching"]
     },
     {
       "package": "bcp/config",
@@ -44,10 +35,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-config",
       "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs.",
-      "guides": [
-        "/docs/configuration",
-        "/docs/environment-validation"
-      ]
+      "guides": ["/docs/configuration", "/docs/environment-validation"]
     },
     {
       "package": "bcp/validation",
@@ -55,9 +43,7 @@
       "environment": "universal",
       "route": "/docs/api-reference#bcp-validation",
       "summary": "Typed validators, parse helpers and structured validation errors.",
-      "guides": [
-        "/docs/validation"
-      ]
+      "guides": ["/docs/validation"]
     },
     {
       "package": "bcp/error",
@@ -65,9 +51,7 @@
       "environment": "universal",
       "route": "/docs/api-reference#bcp-error",
       "summary": "Structured HTTP error creation, classification and response helpers.",
-      "guides": [
-        "/docs/error-handling"
-      ]
+      "guides": ["/docs/error-handling"]
     },
     {
       "package": "bcp/database",
@@ -75,11 +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",
@@ -87,13 +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",
@@ -101,13 +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/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",
@@ -115,11 +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/observability"
-      ]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability"]
     },
     {
       "package": "bcp/events",
@@ -127,12 +91,23 @@
       "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/observability"
-      ]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability"]
+    },
+    {
+      "package": "bcp/realtime",
+      "source": "packages/client/src/realtime.ts",
+      "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/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",
@@ -140,10 +115,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-observability",
       "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
-      "guides": [
-        "/docs/observability",
-        "/docs/development-logging"
-      ]
+      "guides": ["/docs/observability", "/docs/development-logging"]
     },
     {
       "package": "bcp/server",
@@ -151,14 +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",
@@ -166,9 +131,7 @@
       "environment": "server-marker",
       "route": "/docs/api-reference#bcp-server-only",
       "summary": "Server-only module boundary marker that prevents accidental browser inclusion.",
-      "guides": [
-        "/docs/application-modules"
-      ]
+      "guides": ["/docs/application-modules"]
     },
     {
       "package": "bcp/middleware",
@@ -176,9 +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"]
     }
   ]
 }