docs(scaffold,tests_create): document the two-pattern test split (hero_rpc#115) #284

Open

timur wants to merge 1 commit from issue-115-tests-docs into development

timur commented

2026-05-21 23:39:33 +00:00

Owner

Summary

Updates hero_service_scaffold.md to document the --no-tests flag, add tests/ to the post-scaffold file-tree block, and add a new ## End-to-end tests — out of the box (hero_rpc#115) section parallel to the existing UI scaffolds block.
Updates hero_tests_create.md so it no longer collides with the scaffolded tests/ pattern — adds a "When to use this vs. the workspace-root tests/ crate" comparison at the top.

Why

hero_rpc#115 / PR #119 lands a new test pattern: workspace-root tests/ crate with per-rootobject #[tokio::test] integration tests spun up in-process via hero_rpc_osis::rpc::bootstrap::run_for_test. That coexists with — does not replace — the canonical crates/hero_<svc>_test/ pattern documented in hero_tests_create.md.

The two patterns answer different questions:

	`tests/` (scaffolded by #115)	`crates/hero_<svc>_test/` (hero_tests_create)
Validates	codegen-emitted CRUD surface	deployed service in realistic scenarios
Runs when	every `cargo test` (CI / dev loop)	ops / QA after `lab service --start --force --build`
Server	in-process per test	already running, hero_proc-registered
Style	Cargo `[[test]]` + `#[tokio::test]`	clap CLI + `run_test_filtered` + error files
Setup cost	none	`lab service --start --force --build` first

Without this docs alignment, the two patterns look conflicting. With it, the split is intentional and discoverable from either entry point.

Test plan

hero_service_scaffold.md — --no-tests row added to flags table; .with_tests() shown in library-API example; tests/ block added to the file tree; new "End-to-end tests — out of the box" section parallels the existing UI section + ends with the "When to use vs. crates/hero__test/" subtable.
hero_tests_create.md — Purpose paragraph reframed to "self-contained binary for ops / QA integration coverage of a deployed service"; new "When to use this pattern vs. the workspace-root tests/ crate" section at the top with the same comparison table and a forward link to hero_service_scaffold.
Reviewer spot-check: cross-links between the two docs resolve (hero_tests_create → hero_service_scaffold and back).

Follow-up

Companion to hero_rpc PR #119. Merge after #119 lands.

🤖 Generated with Claude Code

## Summary - Updates `hero_service_scaffold.md` to document the `--no-tests` flag, add `tests/` to the post-scaffold file-tree block, and add a new `## End-to-end tests — out of the box (hero_rpc#115)` section parallel to the existing UI scaffolds block. - Updates `hero_tests_create.md` so it no longer collides with the scaffolded `tests/` pattern — adds a "When to use this vs. the workspace-root `tests/` crate" comparison at the top. ## Why [hero_rpc#115](https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/115) / [PR #119](https://forge.ourworld.tf/lhumina_code/hero_rpc/pulls/119) lands a new test pattern: workspace-root `tests/` crate with per-rootobject `#[tokio::test]` integration tests spun up in-process via `hero_rpc_osis::rpc::bootstrap::run_for_test`. That coexists with — does not replace — the canonical `crates/hero_<svc>_test/` pattern documented in `hero_tests_create.md`. The two patterns answer different questions: | | `tests/` (scaffolded by #115) | `crates/hero_<svc>_test/` (hero_tests_create) | |---|---|---| | Validates | codegen-emitted CRUD surface | deployed service in realistic scenarios | | Runs when | every `cargo test` (CI / dev loop) | ops / QA after `lab service --start --force --build` | | Server | in-process per test | already running, hero_proc-registered | | Style | Cargo `[[test]]` + `#[tokio::test]` | clap CLI + `run_test_filtered` + error files | | Setup cost | none | `lab service --start --force --build` first | Without this docs alignment, the two patterns look conflicting. With it, the split is intentional and discoverable from either entry point. ## Test plan - [x] `hero_service_scaffold.md` — `--no-tests` row added to flags table; `.with_tests()` shown in library-API example; `tests/` block added to the file tree; new "End-to-end tests — out of the box" section parallels the existing UI section + ends with the "When to use vs. crates/hero_<svc>_test/" subtable. - [x] `hero_tests_create.md` — Purpose paragraph reframed to "self-contained binary for ops / QA integration coverage of a deployed service"; new "When to use this pattern vs. the workspace-root tests/ crate" section at the top with the same comparison table and a forward link to `hero_service_scaffold`. - [ ] Reviewer spot-check: cross-links between the two docs resolve (`hero_tests_create` → `hero_service_scaffold` and back). ## Follow-up Companion to hero_rpc PR [#119](https://forge.ourworld.tf/lhumina_code/hero_rpc/pulls/119). Merge after #119 lands. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

timur added 1 commit

2026-05-21 23:39:33 +00:00

docs(scaffold,tests_create): document the two-pattern test split (hero_rpc#115) e346208dd4

`tests/` (the workspace-root crate scaffolded by hero_rpc#115) and
`crates/hero_<svc>_test/` (the canonical hero_tests_create pattern)
both exist intentionally — they answer different questions:

- `tests/` — codegen E2E, `cargo test`, in-process via run_for_test,
  no operator setup. Validates "did the scaffolder emit a working
  CRUD surface?".
- `crates/hero_<svc>_test/` — service integration, categorised clap
  CLI against a running server. Validates "does the deployed service
  hold up under realistic scenarios?".

Updates:

`hero_service_scaffold.md`
- `--no-tests` added to the CLI flags table + the library-API example
  (`.with_tests()` shown as default).
- `tests/` added to the post-scaffold file-tree block.
- New `## End-to-end tests — out of the box (hero_rpc#115)` section
  parallel to the existing `## UI scaffolds — out of the box` block,
  with a "When to use this vs. crates/hero_<svc>_test/" subtable that
  draws the line between the two patterns.

`hero_tests_create.md`
- Opening paragraph reframed: "every Hero service needs" → "self-
  contained binary for ops / QA integration coverage of a deployed
  service". The previous framing collided with the new scaffolded
  `tests/` once #115 landed.
- New `## When to use this pattern vs. the workspace-root tests/
  crate` section at the top of the doc with the same two-pattern
  comparison table, plus a forward pointer to `hero_service_scaffold`
  for the scaffolded path.

No code in this commit — pure docs alignment for the post-#115
scaffold surface.

This pull request has changes conflicting with the target branch.

skills/hero/service/hero_service_scaffold.md

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin issue-115-tests-docs:issue-115-tests-docs

git switch issue-115-tests-docs

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch development

git merge --no-ff issue-115-tests-docs

git switch issue-115-tests-docs

git rebase development

git switch development

git merge --ff-only issue-115-tests-docs

git switch issue-115-tests-docs

git rebase development

git switch development

git merge --no-ff issue-115-tests-docs

git switch development

git merge --squash issue-115-tests-docs