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>

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

@@ -261,6 +261,68 @@ Supporting helpers for composing custom test patterns:
 - `decode_frames_with_codec` — decode wire bytes to frames.
 - `extract_payloads` — extract payload bytes from decoded frames.
 
+#### 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 you can exercise your codec's buffering logic 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

@@ -29,6 +29,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,204 @@
+//! 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 env = Envelope::new(1, Some(7), vec![u8::try_from(i).unwrap_or(0)]);
+            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(())
+    }
+}