Guides on Orchard

Seeding a demo environment

Mon, 01 Jan 0001 00:00:00 +0000

Seeding a demo environment#

Goal. Produce a database that tells a compelling story when someone opens the product. Not just rows — a believable narrative: customers with histories, orders with realistic timing, payments with a mix of outcomes.

Why Orchard. Hand-written SQL seed scripts rot. They drift from the schema, they can’t vary the story for different audiences, and they don’t compose. A scenario describes the story once; variables let you reshape it per demo.

Manual UAT testing

Mon, 01 Jan 0001 00:00:00 +0000

Manual UAT testing#

Goal. Reproducible test cases for QA and stakeholders. “A subscription with three failed payments” should be one command, not a fifteen-minute click-through.

Why Orchard. UAT scripts usually live as a README page of SQL snippets, a shared Notion doc, or inside someone’s head. Turning them into scenarios makes them runnable, version-controlled, and reviewable.

Pattern: test case per scenario#

Each distinct UAT case becomes a scenario file. Name them after the test case:

Local development environments

Mon, 01 Jan 0001 00:00:00 +0000

Local development environments#

Goal. New engineers clone the repo, run one command, and have a working local database with enough data to develop against. No “ask Slack for a SQL dump.”

Why Orchard. A single authoritative scenario replaces the tribal-knowledge approach. The scenario lives in the repo and evolves with the schema.

Pattern: one “dev” scenario per service#

scenarios/
└── dev.hcl

dev.hcl is the canonical “everything you need to boot up locally.” Engineers run it after applying migrations.

Integration testing

Mon, 01 Jan 0001 00:00:00 +0000

Integration testing#

Goal. Shared, versioned setup for your integration test suite. Each test needs a predictable slice of the database; Orchard produces that slice from a scenario.

Why Orchard. Integration tests tend to accumulate setup code in Go/Python/ whatever — createMerchant(t, db, "Acme") functions that duplicate what your product already does. Orchard scenarios are a source of truth that both tests and local dev can share.

Pattern: scenario per test fixture#

test/
├── integration/
│ ├── fixtures/
│ │ ├── empty.hcl
│ │ ├── one_merchant.hcl
│ │ └── merchant_with_orders.hcl
│ └── ...

Each test declares which fixture it needs and runs that scenario as part of setup.

Composing components

Mon, 01 Jan 0001 00:00:00 +0000

Composing components#

Goal. Break a large scenario down into reusable components. Think of components like functions: small, well-named, tested in isolation, reused across scenarios.

When to extract a component#

Extract a component when you notice one of these signals:

Repetition. The same 5–10 lines of HCL appear in three scenarios. Make them a component.
Named concepts. When you find yourself wanting to say “a merchant” instead of “three SQL inserts and two HTTP calls”, you’ve found the component boundary.
Scope variation. A small concept today might need to expand. A component gives you a single place to change behavior for all callers.

Don’t extract: