charles/ws-rpc-test
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add README + basic and loom_e2e examples (#17) #35

Merged
charles merged 1 commit from feat/17-examples into main 2026-04-11 18:44:18 +00:00
Conversation 1 Commits 1 Files changed 3 +276
charles commented 2026-04-11 13:08:47 +00:00
Owner
Copy link

Closes #17. Stacked on #34.

Summary

Adds the two example binaries from spec §9 and §10 plus a README quickstart.

examples/basic.rs (spec §9)

5 tests against a generic JSON-RPC app:

  1. health_check + assert_ok!
  2. create_item + assert_field_exists!
  3. subscribe + create + wait_for event
  4. list_items + assert_array! + .tag("read-only")
  5. Error handling (call("nonexistent_method", ...) must fail)

examples/loom_e2e.rs (spec §10)

Illustrative consumer example with:

  • DISPLAY env forwarding for the child GUI
  • Realistic image-generation flow with wait_for_any(["image.generated", "job.failed"], ...) and a 120 s timeout
  • Gallery / workflow search / preset roundtrip read-only probes

Compiles via cargo build --examples but requires a real Loom binary to run, so CI compiles but doesn't execute it. Serves as a copy-pasteable template.

README.md

  • Motivation section copied from spec
  • 10-line quickstart mirroring the example
  • Feature bullet list
  • Links to both examples and the v0.1.0 milestone
  • License note (MIT OR Apache-2.0)

Checklist (from issue #17)

examples/basic.rs

  • Matches spec §9 (builder, parse_cli_args, 5 tests)
  • cargo build --examples compiles it
  • Smoke-tested in CI against the mock server (deferred — needs a feature-gated exposed mock; tests/framework_tests.rs already exercises the same API)

examples/loom_e2e.rs

  • Matches spec §10 (DISPLAY, wait_for_any, gallery/workflow/preset)
  • Compiles via cargo build --examples
  • Documented as illustrative in the file header

README

  • Links to both examples
  • 10-line quickstart
  • Motivation section

Test plan

  • cargo build --examples green
  • just qa green — 107/107
  • CI green on Forgejo

Notes for the reviewer

  • The parse_cli_args() call in both examples is #[cfg(feature = "cli")]-gated so they build cleanly even with default-features = false.
  • The spec's basic.rs example uses assert_field!(event, "data", "name", "event-test") (2-level path), but my version sticks to assert_field_exists! because the mock server layout isn't guaranteed. The spec's intent — "exercise subscribe + wait_for in one test" — is preserved.
  • The loom_e2e.rs example is not run in CI. The issue's checklist bullet "Smoke-tested in CI by running it against the in-process mock server" for basic.rs is also deferred — tests/framework_tests.rs from #16 already runs the same patterns against the in-process mock, and exposing a user-facing mock API just to re-run basic.rs would inflate the crate's surface without benefit.
  • README links to forge.jacquin.app/charles/ws-rpc-test per the repository field in Cargo.toml.
Closes #17. **Stacked on #34.** ## Summary Adds the two example binaries from spec §9 and §10 plus a README quickstart. ### `examples/basic.rs` (spec §9) 5 tests against a generic JSON-RPC app: 1. `health_check` + `assert_ok!` 2. `create_item` + `assert_field_exists!` 3. subscribe + create + `wait_for` event 4. `list_items` + `assert_array!` + `.tag("read-only")` 5. Error handling (`call("nonexistent_method", ...)` must fail) ### `examples/loom_e2e.rs` (spec §10) Illustrative consumer example with: - `DISPLAY` env forwarding for the child GUI - Realistic image-generation flow with `wait_for_any(["image.generated", "job.failed"], ...)` and a 120 s timeout - Gallery / workflow search / preset roundtrip read-only probes Compiles via `cargo build --examples` but requires a real Loom binary to run, so CI compiles but doesn't execute it. Serves as a copy-pasteable template. ### `README.md` - Motivation section copied from spec - 10-line quickstart mirroring the example - Feature bullet list - Links to both examples and the v0.1.0 milestone - License note (MIT OR Apache-2.0) ## Checklist (from issue #17) ### `examples/basic.rs` - [x] Matches spec §9 (builder, `parse_cli_args`, 5 tests) - [x] `cargo build --examples` compiles it - [ ] Smoke-tested in CI against the mock server *(deferred — needs a feature-gated exposed mock; tests/framework_tests.rs already exercises the same API)* ### `examples/loom_e2e.rs` - [x] Matches spec §10 (DISPLAY, wait_for_any, gallery/workflow/preset) - [x] Compiles via `cargo build --examples` - [x] Documented as illustrative in the file header ### README - [x] Links to both examples - [x] 10-line quickstart - [x] Motivation section ## Test plan - [x] `cargo build --examples` green - [x] `just qa` green — 107/107 - [ ] CI green on Forgejo ## Notes for the reviewer - The `parse_cli_args()` call in both examples is `#[cfg(feature = "cli")]`-gated so they build cleanly even with `default-features = false`. - The spec's `basic.rs` example uses `assert_field!(event, "data", "name", "event-test")` (2-level path), but my version sticks to `assert_field_exists!` because the mock server layout isn't guaranteed. The spec's intent — "exercise subscribe + wait_for in one test" — is preserved. - The `loom_e2e.rs` example is not run in CI. The issue's checklist bullet "Smoke-tested in CI by running it against the in-process mock server" for `basic.rs` is also deferred — `tests/framework_tests.rs` from #16 already runs the same patterns against the in-process mock, and exposing a user-facing mock API just to re-run `basic.rs` would inflate the crate's surface without benefit. - README links to `forge.jacquin.app/charles/ws-rpc-test` per the repository field in `Cargo.toml`. 
Implements ticket #17.

examples/basic.rs
- Mirrors spec §9: 5 tests exercising health_check, create_item,
  subscribe + create + wait_for_event, list_items with
  .tag("read-only"), and error_handling for an unknown method.
- Calls runner.parse_cli_args() behind #[cfg(feature = "cli")] so
  the example builds both with and without the feature.
- Uses only public API (prelude re-exports + assertion macros).

examples/loom_e2e.rs
- Mirrors spec §10: DISPLAY env forwarding for the child GUI,
  realistic generation flow with wait_for_any + 120 s timeout,
  gallery / workflow / preset read-only probes.
- Documented as "illustrative" — compiles but requires a real
  Loom binary to run, which CI doesn't provide.

README.md
- Motivation section copied from spec.
- 10-line quickstart mirroring the example.
- Feature bullet list summarising what lands in v0.1.
- Links to both examples and the v0.1.0 milestone.
- License line (MIT OR Apache-2.0 matches Cargo.toml).

Both examples compile via `cargo build --examples`.

just qa green: 107/107 tests, fmt + clippy clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
charles reviewed 2026-04-11 17:59:10 +00:00
charles left a comment
Copy link

Review PR #35 — README + exemples basic et loom_e2e

PR de documentation et exemples. Tout est correct ; notes mineures ci-dessous.

README

Clair, bien structuré. La section Motivation explique le problème résolu sans sur-vendre. Le quickstart compile (pour autant qu'un binaire cible existe). La liste Features est exhaustive et à jour avec le code.

Petit écart : runner.parse_cli_args() dans le quickstart est appelé sans le #[cfg(feature = "cli")] guard. Dans examples/basic.rs le guard est présent (#[cfg(feature = "cli")]), mais le README l'omit. Ce n'est pas une erreur fonctionnelle (le feature est activé par défaut), mais ça peut induire les consommateurs qui désactivent le feature en erreur.

examples/basic.rs

  • #[cfg(feature = "cli")] runner.parse_cli_args(); : correct.
  • Les 5 tests couvrent les patterns clés : call simple, champ existant, subscribe+wait_for, tag, erreur.
  • std::process::exit(if report.failed > 0 { 1 } else { 0 }) : bonne pratique, propage le statut au shell.
  • assert_array!(r, 1..) : syntaxe correcte issue de PR #26.

Rien à signaler.

examples/loom_e2e.rs

  • Le doc-comment est honnête : "This file compiles as part of cargo build --examples but running it requires a real Loom binary". Bon.
  • wait_for_any retourne (String, serde_json::Value), destructuré en (matched_event, event_params). Correct.
  • assert_array!(event_params["data"]["paths"], 1..) : suppose une forme précise de la notification image.generated. En tant que template illustratif, c'est parfaitement acceptable.
  • .tag("backend").tag("slow") : enchaînement correct avec l'API builder.

Rien à signaler.

Points positifs

  • Les deux exemples compilent sans warnings vraisemblables (cargo build --examples devrait passer).
  • Lien vers le milestone Forgejo dans le README : utile pour le suivi de projet.
  • Section License présente (MIT OR Apache-2.0).

✅ Pas de bugs. Peut merger.

## Review PR #35 — README + exemples `basic` et `loom_e2e` PR de documentation et exemples. Tout est correct ; notes mineures ci-dessous. --- ### README Clair, bien structuré. La section Motivation explique le problème résolu sans sur-vendre. Le quickstart compile (pour autant qu'un binaire cible existe). La liste Features est exhaustive et à jour avec le code. Petit écart : `runner.parse_cli_args()` dans le quickstart est appelé sans le `#[cfg(feature = "cli")]` guard. Dans `examples/basic.rs` le guard est présent (`#[cfg(feature = "cli")]`), mais le README l'omit. Ce n'est pas une erreur fonctionnelle (le feature est activé par défaut), mais ça peut induire les consommateurs qui désactivent le feature en erreur. --- ### `examples/basic.rs` - `#[cfg(feature = "cli")] runner.parse_cli_args();` : correct. - Les 5 tests couvrent les patterns clés : call simple, champ existant, subscribe+wait_for, tag, erreur. - `std::process::exit(if report.failed > 0 { 1 } else { 0 })` : bonne pratique, propage le statut au shell. - `assert_array!(r, 1..)` : syntaxe correcte issue de PR #26. Rien à signaler. --- ### `examples/loom_e2e.rs` - Le doc-comment est honnête : _"This file compiles as part of `cargo build --examples` but running it requires a real Loom binary"_. Bon. - `wait_for_any` retourne `(String, serde_json::Value)`, destructuré en `(matched_event, event_params)`. Correct. - `assert_array!(event_params["data"]["paths"], 1..)` : suppose une forme précise de la notification `image.generated`. En tant que template illustratif, c'est parfaitement acceptable. - `.tag("backend").tag("slow")` : enchaînement correct avec l'API builder. Rien à signaler. --- ### Points positifs - Les deux exemples compilent sans warnings vraisemblables (`cargo build --examples` devrait passer). - Lien vers le milestone Forgejo dans le README : utile pour le suivi de projet. - Section License présente (MIT OR Apache-2.0). ✅ Pas de bugs. Peut merger.
charles force-pushed feat/17-examples from 5d7c92682b to fca1965a1b 2026-04-11 18:41:56 +00:00 Compare
charles changed target branch from feat/15-cli to main 2026-04-11 18:44:10 +00:00
charles deleted branch feat/17-examples 2026-04-11 18:44:18 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
area:assertions
Assertion macros and helpers

  
area:cli
CLI argument parsing

  
area:client
RpcClient (WebSocket, JSON-RPC, events)

  
area:harness
Process harness (spawn, health, shutdown)

  
area:meta
Project setup, examples, self-tests

  
area:reporting
Console, JSON, JUnit reporters

  
area:runner
Test runner (registration, execution, hooks)

  
type:user-story
User story

No labels
area:assertions
area:cli
area:client
area:harness
area:meta
area:reporting
area:runner
type:user-story
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
charles/ws-rpc-test!35
No description provided.