Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions docs/wireframe-testing-crate.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ frames, enabling fast tests without opening real network connections.

The existing tests in [`tests/`](../tests) use helper functions such as
`run_app_with_frame` and `run_app_with_frames` to feed length‑prefixed frames
through an in‑memory duplex stream. These helpers simplify testing handlers by
allowing assertions on encoded responses without spinning up a full server.
through an in‑memory duplex stream. These helpers simplify testing handlers
by allowing assertions on encoded responses without spinning up a full server.
Encapsulating this logic in a dedicated crate keeps test code concise and
reusable across projects.

Expand Down Expand Up @@ -50,7 +50,7 @@ The crate would live in a `wireframe_testing/` directory alongside the main
```rust
use tokio::io::Result as IoResult;
use wireframe::app::WireframeApp;
use bincode::Encode;
use serde::Serialize;

/// Feed a single frame into `app` using an in-memory duplex stream.
pub async fn drive_with_frame(app: WireframeApp, frame: Vec<u8>) -> IoResult<Vec<u8>>;
Expand All @@ -61,12 +61,12 @@ pub async fn drive_with_frames(app: WireframeApp, frames: Vec<Vec<u8>>) -> IoRes
/// Encode `msg` with `bincode`, wrap it in a frame, and drive the app.
pub async fn drive_with_bincode<M>(app: WireframeApp, msg: M) -> IoResult<Vec<u8>>
where
M: bincode::Encode;
M: Serialize;
```

These functions mirror the behaviour of `run_app_with_frame` and
`run_app_with_frames` found in the repository’s test utilities. They create a
`tokio::io::duplex` stream, spawn the application as a background task, and
`run_app_with_frames` found in the repository’s test utilities. They create
a `tokio::io::duplex` stream, spawn the application as a background task, and
write the provided frame(s) to the client side of the stream. After the app
finishes processing, the helpers collect the bytes written back and return them
for inspection.
Expand All @@ -78,8 +78,8 @@ these failure conditions directly.

### Custom Buffer Capacity

A variant accepting a buffer `capacity` allows fine‑tuning the size of the
in‑memory duplex channel, matching the existing
A variant accepting a buffer `capacity` allows fine‑tuning the
size of the in‑memory duplex channel, matching the existing
`run_app_with_frame_with_capacity` and `run_app_with_frames_with_capacity`
helpers.

Expand All @@ -106,13 +106,13 @@ pub async fn drive_with_frames_mut(app: &mut WireframeApp, frames: Vec<Vec<u8>>)
### Bincode Convenience Wrapper

For most tests the input frame is preassembled from raw bytes. A small wrapper
can accept any `bincode::Encode` value and perform the encoding and framing
before delegating to `drive_with_frame`. This mirrors the patterns in
`tests/routes.rs` where structs are converted to bytes with `BincodeSerializer`
and then wrapped in a length‑prefixed frame.
can accept any `serde::Serialize` value and perform the encoding and framing
before delegating to `drive_with_frame`. This mirrors the patterns in `tests/
routes.rs` where structs are converted to bytes with `BincodeSerializer` and
then wrapped in a length‑prefixed frame.

Comment on lines 108 to 113
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Wrap long sentence at 80 columns.

The two changed lines exceed the documentation style-guide limit. Wrap them to maintain consistency with the rest of the file and silence markdownlint MD013.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~108-~108: Possible missing comma found.
Context: ...# Bincode Convenience Wrapper For most tests the input frame is preassembled from ra...

(AI_HYDRA_LEO_MISSING_COMMA)

🤖 Prompt for AI Agents
In docs/wireframe-testing-crate.md around lines 108 to 113, the two sentences
exceed the 80-column limit set by the documentation style guide. Break these
long lines into shorter lines, each not exceeding 80 characters, to maintain
consistency and comply with markdownlint MD013 rules.

```rust
#[derive(bincode::Encode)]
#[derive(serde::Serialize)]
struct Ping(u8);

let bytes = drive_with_bincode(app, Ping(1)).await.unwrap();
Expand Down Expand Up @@ -155,6 +155,6 @@ with prebuilt frames and their responses decoded for assertions.

## Next Steps

Implement the crate in a new directory, export the helper functions, and migrate
existing tests to use them. Additional fixtures (e.g., prebuilt frame
Implement the crate in a new directory, export the helper functions, and
migrate existing tests to use them. Additional fixtures (e.g., prebuilt frame
processors) can be added over time as test coverage grows.
2 changes: 1 addition & 1 deletion wireframe_testing/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
//!
//! These helpers spawn the application on a `tokio::io::duplex` stream and
//! return all bytes written by the app for easy assertions. They work with any
//! message implementing [`bincode::Encode`] – the example uses a simple `u8`
//! message implementing [`serde::Serialize`] – the example uses a simple `u8`
//! value so no generics are required.
Comment on lines +6 to 7
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Clarify the serializer expectation.

State explicitly that the helpers still use bincode under the hood. “Any message implementing serde::Serialize” is correct, but without mentioning the concrete encoder the reader might assume a generic serialisation mechanism.
Example wording:

“…work with any message implementing serde::Serialize; the payload is currently encoded with bincode before framing.”

🤖 Prompt for AI Agents
In wireframe_testing/src/lib.rs around lines 6 to 7, clarify the documentation
comment to explicitly state that the serialization uses the bincode encoder.
Update the comment to mention that while the helpers accept any message
implementing serde::Serialize, the payload is currently encoded with bincode
before framing, to avoid confusion about the serialization mechanism.

//!
//! ```rust
Expand Down