Document rstest-bdd Wireframe server harness design

[leynos]

Summary

• design an in-process rstest-bdd v0.6.0-beta3 harness for mxd Wireframe server behavioural tests
• retain a narrow subprocess layer for executable, CLI, and environment wiring
• document the usable wireframe_testing components and the gaps that prevent reuse of WireframePair
• index the design in the documentation contents

Design

The proposed MxdWireframeHarness injects a cloneable scenario context into synchronous steps. A dedicated operating-system thread owns a current-thread Tokio runtime, the test database, the production Wireframe server, and a typed Hotline client. Steps send typed commands to that driver rather than entering the runtime themselves.

This shape accounts for a v0.6.0-beta3 constraint: harness-backed asynchronous steps that yield Pending receive only one poll. A continuously driven server thread therefore avoids nested runtime calls and lets real network and database futures complete.

The design proposes a small test-support server seam that reuses the production application factory, binds an existing listener, forces one worker, exposes readiness, and supports bounded shutdown.

wireframe_testing assessment

The design reuses unused_listener() immediately and recommends its codec, fragment, and opt-in observability helpers where appropriate. It does not use the current WireframePair because:

1. the client is fixed to Wireframe's length-delimited codec;
2. the builder callback cannot change the preamble typestate;
3. server preamble and handshake configuration are not injectable;
4. callers cannot supply a protocol-specific client connector; and
5. no server-only running handle exists.

It proposes an upstream server lifecycle primitive plus a generic client factory, allowing the existing pair API to remain as a compatibility wrapper.

Impact

This is a design-only change. It adds no runtime code and changes no server behaviour.

Validation

• reviewed the design against the current mxd server bootstrap, behavioural worlds, and database fixtures
• reviewed wireframe_testing v0.3.0 pair, listener, codec, fragment, and observability APIs
• reviewed the Skyjoust Bevy harness design and rstest-bdd v0.6.0-beta3 harness and macro behaviour
• confirmed the branch contains only the design document and its contents entry

No code, formatting, lint, or test commands were run because this pull request contains documentation only and the connected environment does not provide a local repository checkout.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9606d0e1-3621-4364-a76a-2fa22560a9fe

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/rstest-bdd-wireframe-harness-design

---

_{Comment @coderabbitai help to get the list of available commands.}

[codescene-access]

No application code in the PR — skipped Code Health checks.

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-access]

No quality gates enabled for this code.