Add utilities for feeding partial frames and fragments (tests, docs, re-exports) (#493)

* feat(testing): add utilities for feeding partial frames and fragments into in-process app

- Introduced chunked-write drivers to write codec-encoded payloads in configurable byte-sized chunks, simulating partial-frame network reads.
- Added fragment-feeding drivers that fragment raw payloads, encode fragments, and feed them through WireframeApp.
- Provided multiple driver variants: owned app, mutable app, with capacity, returning raw frames or payloads.
- Established comprehensive BDD test suite and unit tests covering chunked and fragmented feeding scenarios.
- Updated docs/users-guide.md with new "Feeding partial frames and fragments" section including usage examples.
- Marked roadmap item 8.5.1 as done in docs/roadmap.md.
- Registered modules and re-exported public APIs in wireframe_testing crate.

These utilities enable testing realistic network conditions where frames arrive across multiple reads or are fragmented, improving codec and application robustness validation.

Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>

* refactor(helpers): introduce ChunkConfig and FragmentRequest structs for config

- Added ChunkConfig to combine chunk size and duplex buffer capacity in partial_frame.
- Added FragmentRequest to bundle fragmenter, payload, and capacity in fragment_drive.
- Updated relevant functions to use these structs for clearer and more flexible configuration.
- Refactored partial frame tests for reusability using a helper test function.

Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>

* feat(wireframe_testing): wrap fragment payloads in serialized Envelopes

Fragment payloads are now wrapped inside serialized `Envelope` packets before being fed through the codec and application pipeline. This ensures the application's deserializer accepts these fragment frames instead of accumulating deserialization failures and closing connections.

- Updated fragment_and_encode to wrap `FRAG`-prefixed fragment bytes into `Envelope` packets serialized with `BincodeSerializer`.
- Adjusted fragment feeding tests to verify envelope deserialization and responses.
- Improved documentation and examples in wireframe_testing helpers to reflect the new envelope wrapping.
- Added default route ID for wrapped fragments matching typical app route registrations.

This enhancement makes fragment feeding tests more accurate by fully simulating the expected codec and application message framing.

Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>

* test(partial_frame_feeding): update test terminology and assertions for fragment feeding

- Corrected spelling of 'parameterised' to 'parameterized' in comments.
- Updated test scenario assertions from 'app receives fragment frames' to 'fragment feeding completed'.
- Replaced `response_frames` field with `fragment_feeding_completed` boolean in test fixture.
- Changed assertion helpers to check for fragment feeding completion instead of received fragments.

These changes improve clarity and accuracy of partial frame feeding tests.

Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>

---------

Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>

Author: leynos

docs/execplans/8-5-1-utilities-for-feeding-partial-frames-into-in-process-app.md

@@ -313,7 +313,7 @@ and standardized per-connection memory budgets.
 
 ### 8.5. Testkit utilities
 
-- [ ] 8.5.1. Add utilities for feeding partial frames or fragments into an
+- [x] 8.5.1. Add utilities for feeding partial frames or fragments into an
   in-process app.
 - [ ] 8.5.2. Add slow reader and writer simulation for back-pressure testing.
 - [ ] 8.5.3. Add deterministic assertion helpers for reassembly outcomes.

docs/roadmap.md

@@ -305,6 +305,67 @@ Available fixture functions:
 - `correlated_hotline_wire` — frames sharing a transaction ID.
 - `sequential_hotline_wire` — frames with incrementing transaction IDs.
 
+#### Feeding partial frames and fragments
+
+Real networks rarely deliver a complete codec frame in a single TCP read.
+The `wireframe_testing` crate provides drivers that simulate these
+conditions so that codec buffering logic can be exercised in tests.
+
+**Chunked-write drivers** encode payloads via a codec, concatenate the wire
+bytes, and write them in configurable chunk sizes (including one byte at a
+time):
+
+```rust,no_run
+use std::num::NonZeroUsize;
+use wireframe::app::WireframeApp;
+use wireframe::codec::examples::HotlineFrameCodec;
+use wireframe_testing::drive_with_partial_frames;
+
+let codec = HotlineFrameCodec::new(4096);
+let app = WireframeApp::new()?.with_codec(codec.clone());
+let chunk = NonZeroUsize::new(1).expect("non-zero");
+let payloads =
+    drive_with_partial_frames(app, &codec, vec![vec![1, 2, 3]], chunk)
+        .await?;
+```
+
+Available chunked-write driver functions:
+
+- `drive_with_partial_frames` / `drive_with_partial_frames_with_capacity` —
+  owned app, returns payload bytes.
+- `drive_with_partial_frames_mut` — mutable app reference, returns payload
+  bytes.
+- `drive_with_partial_codec_frames` — owned app, returns decoded `F::Frame`
+  values.
+
+**Fragment-feeding drivers** accept a raw payload, fragment it with a
+`Fragmenter`, encode each fragment into a codec frame, and feed the frames
+through the app:
+
+```rust,no_run
+use std::num::NonZeroUsize;
+use wireframe::app::WireframeApp;
+use wireframe::codec::examples::HotlineFrameCodec;
+use wireframe::fragment::Fragmenter;
+use wireframe_testing::drive_with_fragments;
+
+let codec = HotlineFrameCodec::new(4096);
+let app = WireframeApp::new()?.with_codec(codec.clone());
+let fragmenter = Fragmenter::new(NonZeroUsize::new(20).unwrap());
+let payloads =
+    drive_with_fragments(app, &codec, &fragmenter, vec![0; 100]).await?;
+```
+
+Available fragment-feeding driver functions:
+
+- `drive_with_fragments` / `drive_with_fragments_with_capacity` — owned
+  app, returns payload bytes.
+- `drive_with_fragments_mut` — mutable app reference, returns payload
+  bytes.
+- `drive_with_fragment_frames` — owned app, returns decoded `F::Frame`
+  values.
+- `drive_with_partial_fragments` — fragment AND feed in chunks,
+  exercising both fragmentation and partial-frame buffering simultaneously.
 #### Zero-copy payload extraction
 
 For performance-critical codecs, use `Bytes` instead of `Vec<u8>` for payload

docs/users-guide.md

@@ -0,0 +1,24 @@
+@partial-frame-feeding
+Feature: Partial frame and fragment feeding utilities
+
+  Scenario: Single payload survives byte-at-a-time chunked delivery
+    Given a wireframe app with a Hotline codec allowing 4096-byte frames for partial feeding
+    When a test payload is fed in 1-byte chunks
+    Then the partial feeding response payloads are non-empty
+
+  Scenario: Multiple payloads survive misaligned chunked delivery
+    Given a wireframe app with a Hotline codec allowing 4096-byte frames for partial feeding
+    When 2 test payloads are fed in 7-byte chunks
+    Then the partial feeding response contains 2 payloads
+
+  Scenario: Fragmented payload is delivered as fragment frames
+    Given a wireframe app with a Hotline codec allowing 4096-byte frames for partial feeding
+    And a fragmenter capped at 20 bytes per fragment for partial feeding
+    When a 100-byte payload is fragmented and fed through the app
+    Then the fragment feeding completes without error
+
+  Scenario: Fragmented payload survives chunked delivery
+    Given a wireframe app with a Hotline codec allowing 4096-byte frames for partial feeding
+    And a fragmenter capped at 20 bytes per fragment for partial feeding
+    When a 100-byte payload is fragmented and fed in 3-byte chunks
+    Then the fragment feeding completes without error

tests/features/partial_frame_feeding.feature

@@ -32,6 +32,7 @@ pub mod message_assembly;
 pub mod message_assembly_inbound;
 pub mod multi_packet;
 pub mod panic;
+pub mod partial_frame_feeding;
 pub mod request_parts;
 pub mod serializer_boundaries;
 pub mod stream_end;

tests/fixtures/mod.rs

@@ -0,0 +1,206 @@
+//! BDD world fixture for partial frame and fragment feeding scenarios.
+//!
+//! Tracks application configuration, fragmenter state, and collected
+//! responses across behavioural test steps.
+
+use std::{num::NonZeroUsize, sync::Arc};
+
+use futures::future::BoxFuture;
+use rstest::fixture;
+use wireframe::{
+    app::{Envelope, WireframeApp},
+    codec::examples::HotlineFrameCodec,
+    fragment::Fragmenter,
+    serializer::{BincodeSerializer, Serializer},
+};
+/// Re-export `TestResult` from `wireframe_testing` for use in steps.
+pub use wireframe_testing::TestResult;
+
+/// BDD world holding the app, codec, fragmenter, and collected responses.
+///
+/// `WireframeApp` does not implement `Debug`, so this type provides a manual
+/// implementation that redacts the app field.
+#[derive(Default)]
+pub struct PartialFrameFeedingWorld {
+    codec: Option<HotlineFrameCodec>,
+    app: Option<WireframeApp<BincodeSerializer, (), Envelope, HotlineFrameCodec>>,
+    fragmenter: Option<Fragmenter>,
+    response_payloads: Vec<Vec<u8>>,
+    fragment_feeding_completed: bool,
+}
+
+impl std::fmt::Debug for PartialFrameFeedingWorld {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PartialFrameFeedingWorld")
+            .field("codec", &self.codec)
+            .field("app", &self.app.as_ref().map(|_| ".."))
+            .field("fragmenter", &self.fragmenter)
+            .field("response_payloads", &self.response_payloads.len())
+            .field(
+                "fragment_feeding_completed",
+                &self.fragment_feeding_completed,
+            )
+            .finish()
+    }
+}
+
+/// Fixture for partial frame feeding scenarios used by rstest-bdd steps.
+///
+/// Note: rustfmt collapses simple fixtures into one line, which triggers
+/// `unused_braces`, so keep `rustfmt::skip`.
+#[rustfmt::skip]
+#[fixture]
+pub fn partial_frame_feeding_world() -> PartialFrameFeedingWorld {
+    PartialFrameFeedingWorld::default()
+}
+
+impl PartialFrameFeedingWorld {
+    /// Configure the app with a `HotlineFrameCodec`.
+    ///
+    /// # Errors
+    /// Returns an error if the app or route registration fails.
+    pub fn configure_app(&mut self, max_frame_length: usize) -> TestResult {
+        let codec = HotlineFrameCodec::new(max_frame_length);
+        let app = WireframeApp::<BincodeSerializer, (), Envelope>::new()?
+            .with_codec(codec.clone())
+            .route(
+                1,
+                Arc::new(|_: &Envelope| -> BoxFuture<'static, ()> { Box::pin(async {}) }),
+            )?;
+        self.codec = Some(codec);
+        self.app = Some(app);
+        Ok(())
+    }
+
+    /// Configure a fragmenter with the given maximum payload per fragment.
+    ///
+    /// # Errors
+    /// Returns an error if the payload cap is zero.
+    pub fn configure_fragmenter(&mut self, max_payload: usize) -> TestResult {
+        let cap = NonZeroUsize::new(max_payload).ok_or("fragment payload cap must be non-zero")?;
+        self.fragmenter = Some(Fragmenter::new(cap));
+        Ok(())
+    }
+
+    /// Drive the app with a single payload chunked into `chunk_size` pieces.
+    ///
+    /// # Errors
+    /// Returns an error if the app or codec is not configured, or driving fails.
+    pub async fn drive_chunked(&mut self, chunk_size: usize) -> TestResult {
+        let app = self.app.take().ok_or("app not configured")?;
+        let codec = self.codec.as_ref().ok_or("codec not configured")?;
+        let chunk = NonZeroUsize::new(chunk_size).ok_or("chunk size must be non-zero")?;
+
+        let env = Envelope::new(1, Some(7), b"bdd-chunked".to_vec());
+        let serialized = BincodeSerializer.serialize(&env)?;
+
+        self.response_payloads =
+            wireframe_testing::drive_with_partial_frames(app, codec, vec![serialized], chunk)
+                .await?;
+        Ok(())
+    }
+
+    /// Drive the app with `count` payloads chunked into `chunk_size` pieces.
+    ///
+    /// # Errors
+    /// Returns an error if the app or codec is not configured, or driving fails.
+    pub async fn drive_chunked_multiple(&mut self, count: usize, chunk_size: usize) -> TestResult {
+        let app = self.app.take().ok_or("app not configured")?;
+        let codec = self.codec.as_ref().ok_or("codec not configured")?;
+        let chunk = NonZeroUsize::new(chunk_size).ok_or("chunk size must be non-zero")?;
+
+        let mut payloads = Vec::with_capacity(count);
+        for i in 0..count {
+            let byte = u8::try_from(i)
+                .map_err(|_| format!("payload index {i} exceeds u8 range; use count <= 256"))?;
+            let env = Envelope::new(1, Some(7), vec![byte]);
+            payloads.push(BincodeSerializer.serialize(&env)?);
+        }
+
+        self.response_payloads =
+            wireframe_testing::drive_with_partial_frames(app, codec, payloads, chunk).await?;
+        Ok(())
+    }
+
+    /// Drive the app with a fragmented payload.
+    ///
+    /// # Errors
+    /// Returns an error if the app, codec, or fragmenter is not configured.
+    pub async fn drive_fragmented(&mut self, payload_len: usize) -> TestResult {
+        let app = self.app.take().ok_or("app not configured")?;
+        let codec = self.codec.as_ref().ok_or("codec not configured")?;
+        let fragmenter = self
+            .fragmenter
+            .as_ref()
+            .ok_or("fragmenter not configured")?;
+
+        let _payloads =
+            wireframe_testing::drive_with_fragments(app, codec, fragmenter, vec![0; payload_len])
+                .await?;
+        self.fragment_feeding_completed = true;
+        Ok(())
+    }
+
+    /// Drive the app with a fragmented payload fed in chunks.
+    ///
+    /// # Errors
+    /// Returns an error if the app, codec, or fragmenter is not configured.
+    pub async fn drive_partial_fragmented(
+        &mut self,
+        payload_len: usize,
+        chunk_size: usize,
+    ) -> TestResult {
+        let app = self.app.take().ok_or("app not configured")?;
+        let codec = self.codec.as_ref().ok_or("codec not configured")?;
+        let fragmenter = self
+            .fragmenter
+            .as_ref()
+            .ok_or("fragmenter not configured")?;
+        let chunk = NonZeroUsize::new(chunk_size).ok_or("chunk size must be non-zero")?;
+
+        let _payloads = wireframe_testing::drive_with_partial_fragments(
+            app,
+            codec,
+            fragmenter,
+            vec![0; payload_len],
+            chunk,
+        )
+        .await?;
+        self.fragment_feeding_completed = true;
+        Ok(())
+    }
+
+    /// Assert that fragment feeding completed without error.
+    ///
+    /// # Errors
+    /// Returns an error if fragment feeding has not been attempted or failed.
+    pub fn assert_fragment_feeding_completed(&self) -> TestResult {
+        if !self.fragment_feeding_completed {
+            return Err("fragment feeding has not completed successfully".into());
+        }
+        Ok(())
+    }
+
+    /// Assert that response payloads are non-empty.
+    ///
+    /// # Errors
+    /// Returns an error if no response payloads were collected.
+    pub fn assert_payloads_non_empty(&self) -> TestResult {
+        if self.response_payloads.is_empty() {
+            return Err("expected non-empty response payloads".into());
+        }
+        Ok(())
+    }
+
+    /// Assert that the response contains exactly `expected` payloads.
+    ///
+    /// # Errors
+    /// Returns an error if the payload count does not match.
+    pub fn assert_payload_count(&self, expected: usize) -> TestResult {
+        let actual = self.response_payloads.len();
+        if actual != expected {
+            return Err(format!("expected {expected} response payloads, got {actual}").into());
+        }
+        Ok(())
+    }
+}