Validation Ship & operate

Test the runtime shape you ship, keep automation thin

Local harness detail stays on the testing pages. This page covers what gets promoted into CI and how automation stays observable.

The local harness pages own and binding nuance. This page owns which checks move into preview validation and release automation.

Best for: CI testing policy and preview validation
Local harness owner: plus binding guides
Important nuance: is not a full drain
Workflow companion

Let the local testing pages own local harness detail

This page used to repeat too much of the local harness story. The better split is simpler: keep behavior, autodiscovery, and binding-specific harness detail on the dedicated testing pages, then use this page for the question “what should actually run in automation?”

That keeps local test design and CI policy from drifting into two slightly different copies of the same documentation.

Testing

Testing overview

Map

Use the map page first when you need to choose between starter tests, the harness page, binding-specific guides, runtime context, or CI-facing validation.

Testing

createTestContext()

Harness

This is the canonical page for autodiscovery, helper timing, transport-aware round-trips, and the real helper behavior.

Testing

Binding testing guides

Binding index

Open these when the binding changes the honest testing posture and the local harness rules are no longer one-size-fits-all.

Cleaner split keeps both pages better

Harness pages own local helper behavior. This page owns what gets promoted and how automation stays readable.

Timing rules that matter in CI

Automation does not need the full harness manual, but it needs the timing rules that produce flaky checks or false confidence.

Promote the check that matches the behavior you need to trust.

When the check depends on...	Prefer	Why
side effects from an HTTP handler	Assert the side effect directly or move to a higher-fidelity check.	returns when the handler resolves, not when every background task drains.
Queue, scheduled, or tail background work	, , or	Those helpers wait for their background work before they return, so they are a better fit for async side-effect assertions.
Binding-specific or transport-specific behavior	The binding guide or page first	Different bindings and bridge-backed values have different honest harness rules, and the local testing pages already own those details.

Wrong completion contract = flaky CI

If a test depends on effects being complete, a plain assertion may be too early.

Promote the smallest useful checks

Ship & operate

Preview operations

Preview lifecycle

Use the preview page when a runtime check depends on preview-scoped resources, scope inspection, or cleanup behavior.

Ship & operate

Production deploys

Deploy targets

Use the production page when the check is really about the deploy target, compiled output, or preflight inspection before release.

Ship & operate

GitHub workflows

CI/CD

Use the workflow page when those promoted checks need to become reviewable Actions jobs with explicit triggers, permissions, and feedback.

1

Prove the behavior locally with or the binding-specific guide first.
2

Choose one or two runtime-shaped smoke checks worth rerunning in CI because they protect the deploy boundary.
3

Use preview validation when routing, preview-owned resources, or branch-scoped behavior is the real risk instead of trying to force every concern through one unit-style check.
4

Publish one visible summary or feedback artifact so reviewers can tell what passed without spelunking through raw logs.

Automation stays thin and observable

Deploy logic and GitHub feedback are separate. Cloudflare state changes stay independent from PR comments, deployment records, or other reporting.

Caller workflows own branch naming, permissions, and feedback decisions. Reusable actions focus on one deploy or one reporting job.

Ship & operate

GitHub workflows

CI/CD

The workflow page owns the supported GitHub Actions patterns for impact checks, reusable actions, preview lanes, production lanes, PR feedback, and cleanup.

One package, one target, one visible result per workflow lane.
Split deploy from feedback so reporting can fail or retry independently.
Prefer summaries, PR comments, or deployment records over raw logs.

Thin workflows age better

When a release is stressful, a small workflow that says what it deploys and what it reports is easier to trust.

Thin preview deploy step

- id: deploy

uses: Refzlund/devflare/.github/actions/devflare-deploy@next

with:

working-directory: apps/documentation

deploy-command: bun run deploy --

preview-scope: \${{ github.head_ref || github.ref_name }}

verify-deployment: 'false'

cloudflare-api-token: \${{ secrets.CLOUDFLARE_API_TOKEN }}

cloudflare-account-id: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Preview operations

The preview registry is D1-backed, giving Devflare durable records of scope and deployment state for reliable cleanup.

Docs release gates

Public exports, schema keys, compiler output, typegen, CLI commands, test helpers, and support stances should fail CI when the docs do not change with them.