@chidchanun/bcp 0.2.12 → 0.2.14

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.