User test scenarios for Forge, the manufacturing ERP from
Armory Works. Cases are written as Markdown with embedded YAML, read
directly by a human or compiled to JSON and driven through the browser-based runner in
test-bed/.
A library of manual test cases describing how a manufacturing-focused ERP should behave across the full lifecycle of a business — from a freshly installed application with no records, through bootstrap, master data, first transactions, first production cycle, and exception handling. Cases are written against industry-standard behavior, not against a particular screen or menu path. If the application cannot accomplish what a case describes, that is a bug in the application, not in the case.
Nothing here is automated. A person reads a case, performs the steps against a running install, and records what happened.
The canonical lifecycle is written — Phases 0 through 5, the onboarding tutorial, the schema,
glossary, flow definitions, and eleven cross-cutting suites — alongside a working Angular runner
in test-bed/ and a build step that compiles the library into it.
Roughly 730 cases, counted as top-level id: keys across docs/:
| Group | Cases |
|---|---|
| Onboarding tutorial | 6 |
| Phase 0 — bootstrap | 22 |
| Phase 1 — foundations | 24 |
| Phase 2 — master data | 40 |
| Phase 3 — first transactions | 30 |
| Phase 4 — production cycle | 31 |
| Phase 5 — exception cycles | 73 |
| Cross-cutting suites | 501 |
Role reference appendices and dedicated internationalization and accessibility suites are not yet written.
Two reference documents in docs/ cover the project in depth:
docs/test-scenarios.md— what the test library is, how it is organized, the schema, conventions, the authoring guide, and how to read and run cases.docs/runner-platform.md— specification for the browser-based runner: architecture, data model, UX flows, build pipeline, and v1 scope.
Read those before contributing. The rest of this README is a quick orientation.
docs/
test-scenarios.md Reference: the test library
runner-platform.md Reference: the test runner
glossary.md Plain-English term definitions
flows.md Cross-phase business journeys
stories.md Role-aware narratives through the gold-path subset
expansion-plan.md Where the library is still thin, and by how much
authoring-prompt.md The prompt used to author new cases
01-schema.md Test case field structure and conventions
02-onboarding-tutorial.md Tutorial cases (TUT-NNN)
03-phase-0-bootstrap.md Phase 0 — bootstrap from an empty database
04-phase-0-manifest.md Phase 0 sequence, branches, checkpoints
05-phase-1-foundations.md Phase 1 — foundational records
06-phase-1-manifest.md Phase 1 sequence, role coverage, checkpoints
07-phase-2-master-data.md Phase 2 — vendors, customers, parts, BOMs, routings, R&D
08-phase-2-manifest.md Phase 2 sequence, checkpoints
09-phase-3-transactions.md Phase 3 — first POs, receipts, commissioning, opening balances
10-phase-3-manifest.md Phase 3 sequence, checkpoints
11-phase-4-production-cycle.md Phase 4 — quote-to-cash and hire-to-first-assignment
12-phase-4-manifest.md Phase 4 sequence, checkpoints
13-phase-5-exception-cycles.md Phase 5 — damage, PM, RMA, period close, traceability, subcontract
14-phase-5-manifest.md Phase 5 sequence, checkpoints
cases/{P0,P3,P4,P5}/ Additional per-phase cases, one topic per file
suites/<name>/ Cross-cutting suites, each with its own manifest.md
test-bed/ Angular SPA runner
VERSION Release version for the runner image
The eleven suites are accounting, audit, bulk-ops, concurrency, documents,
edge-cases, integrations, list-views, notifications, permissions, and reports.
- Authoring format: Markdown with embedded YAML for case structure. The runner consumes a JSON compilation; humans read the source.
- Case IDs:
PHASE-AREA-NNN(for exampleP0-TENANT-001). Tutorial cases useTUT-NNN. IDs are stable — never renumbered, never reused. - Language: Plain industry-standard English. Jargon is treated as a bug in the test case, not a sign of rigor.
- Negative variants: Live with their happy-path parent, not in a separate document.
- Internationalization and Section 508: Covered by dedicated suites against representative screens rather than exhaustively per case. Those suites are not yet written.
- Fictional company: A default fixture (Cascade Components, LLC, a precision sheet metal
fabricator) supplies example values through placeholders such as
{{company_name}}. Other fixtures swap in to scale the same cases up or down.
See docs/01-schema.md for the full schema.
The runner is an Angular SPA backed by IndexedDB. It needs no server and no database — results stay in the tester's browser.
Requirements: Node.js 24 (the version CI builds with) and npm.
cd test-bed
npm install
npm startnpm start runs build:content first, which compiles the Markdown and YAML in docs/ into
test-bed/public/assets/data/*.json, then starts the dev server. Open the URL it prints. Running
ng serve directly skips the content compile and leaves the runner on whatever JSON was last
built.
Other commands, all from test-bed/:
npm run build:content # compile docs/ to runner JSON only
npm run build # production build (compiles content first)
npm test # unit tests (Vitest)To build the container image, note that the build context is the repository root, not
test-bed/, because the content compile reads ../docs:
docker build -f test-bed/Dockerfile .Tagged releases and pushes to main publish multi-architecture images to GitHub Container
Registry through the workflows in .github/workflows/.
Bugs in the application under test: stop at the first non-cosmetic one and report it. Do not work around the problem — the point of the case is that the described workflow should simply work. Those belong on the Forge repo.
Bugs in a test case, the schema, or the runner belong here: github.com/armoryworks/forge-test/issues.