Skip to content
Skills Library
Programming · Testing

ruststream-testing

/ruststream-testing

Use when writing, fixing or reviewing tests of a service built on RustStream: asserting what a handler received, how it settled and what it published, retries and delays without waiting, swapping state for a test double, testing without a running broker or against one. Use it instead of mocking broker traits or sleeping.

Repository
ruststream ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when writing, fixing or reviewing tests of a service built on RustStream: asserting what a handler received, how it settled and what it published, retries and delays without waiting, swapping state for a test double, testing without a running broker or against one. Use it instead of mocking broker traits or sleeping.

Original author description

Use when writing, fixing or reviewing tests of a service built on RustStream: asserting what a handler received, how it settled and what it published, retries and delays without waiting, swapping state for a test double, testing without a running broker or against one. Use it instead of mocking broker traits or sleeping.

How it works

  1. A whole test module
  2. Rules
  3. Quick reference
Original SKILL.md headings · 204 lines, 818 words
SKILL.md preview
---
name: ruststream-testing
description: "Use when writing, fixing or reviewing tests of a service built on RustStream: asserting what a handler received, how it settled and what it published, retries and delays without waiting, swapping state for a test double, testing without a running broker or against one. Use it instead of mocking broker traits or sleeping."
---

# Testing a RustStream service

`TestApp` (the `testing` feature) runs the service's production app, the same builder `main`
runs, with every broker connected in process: no server, no network, no second app for tests.
A publish from the test returns once everything it set off has settled, so the next line can
assert on the result. This guidance targets ruststream 0.7.

```toml
[dev-dependencies]
ruststream = { version = "0.7", features = ["testing"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread", "test-util"] }
# a networked broker crate brings its in-process mode under its own `testing` feature:
# ruststream-nats = { version = "0.7", features = ["testing"] }
```

## A whole test module

The tests sit beside `fn app()` (`#[cfg(test)] mod tests` in the same file, or `tests/` when the
crate has a library target that exports `app`).

```rust
use ruststream::memory::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Deserialize, Serialize, Outgoing)]
struct Event {
    id: u64,
}

#[derive(Debug, PartialEq, Deserialize, Serialize, Outgoing)]
#[outgoing(name = "orders.confirmed")]
struct Confirmed {
    id: u64,
}

#[derive(Debug, PartialEq, Deserialize, Serialize, Outgoing)]
struct Audit {
    id: u64,
}

#[derive(OutSlot)]
#[publishes(Audit)]
struct Trail;

#[subscriber("orders.incoming", reply)]
async fn confirm(
    event: &Event,
    Out(trail): Out<impl Publisher, Trail>,
) -> Result<Confirmed, HandlerOutcome> {
    if event.id == 0 {
        return Err(HandlerOutcome::drop());
    }
    if trail.message(&Audit { id: event.id }).to("audit").publish().await.is_err() {
        return Err(HandlerOutcome::retry());
    }
    Ok(Confirmed { id: event.id })
}

#[ruststream::app]
fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(MemoryBroker::new(), |b| {
        b.include(confirm).out(Trail, Publish).build();
    })
}

#[cfg(test)]
mod tests {
    use std::error::Error;

    use ruststream::memory::prelude::*;
    use ruststream::testing::TestApp;

    use super::{Audit, Confirmed, Event, Trail, app};

    #[tokio::test]
    async fn an_event_is_confirmed_and_audited() -> Result<(), Box<dyn Error>> {
        let tb = TestApp::start(app()).await?;
        let broker = tb.broker::<MemoryBroker>();
        broker.message(&Event { id: 5 }).to("orders.incoming").publish().await?;

        broker
            .subscriber("orders.incoming")
            .assert_called_once()
            .with(&Event { id: 5 })
            .settled(HandlerOutcome::ack());
        broker
            .published::<Confirmed>("orders.confirmed")
            .assert_called_once()
            .with(&Confirmed { id: 5 });
        // What left through one `Out` slot, addressed by its marker.
        tb.out::<Trail>()
            .assert_called_once()
            .decoded_as::<Audit>()
            .with(&Audit { id: 5 });
        Ok(())
    }

    #[tokio::test]
    async fn event_zero_is_dropped_and_nothing_leaves() -> Result<(), Box<dyn Error>> {
        let tb = TestApp::start(app()).await?;
        let broker = tb.broker::<MemoryBroker>();
        broker.message(&Event { id: 0 }).to("orders.incoming").publish().await?;

        broker
            .subscriber("orders.incoming")
            .assert_called_once()
            .settled(HandlerOutcome::drop());
        broker.published::<Confirmed>("orders.confirmed").assert_not_called();
        tb.out::<Trail>().assert_not_called();
        Ok(())
    }
}
```

## Rules

### Address everything through the harness

Records are read from the broker handle by name: `broker.subscriber("subject")` for what a
handler received and how it settled, `broker.published::<T>("destination")` for what reached a
destination, `tb.out::<Marker>()` for what left through one `Out` slot. A handler function is not
an assertion target, and `tb.out` takes a slot marker, not a message type.

Wrong:

```rust
confirm.assert_called(1);
assert_eq!(tb.out::<Confirmed>().received(), vec![Confirmed { id: 5 }]);
```

Correct:

```rust
broker.subscriber("orders.incoming").assert_called(1);
broker.published::<Confirmed>("orders.confirmed").assert_called_once().with(&Confirmed { id: 5 });
```

### Test the production app, addressed by the production broker type

`TestApp::start(app())` takes the builder `main` runs. A networked broker is addressed by its own
type, `tb.broker::<NatsBroker>()`; its crate's `testing` feature runs it in process. Never build
a second app for tests, mock a broker trait, or name a stand-in broker type.

### Never sleep: settle, and advance a paused clock

`publish().await?` already drives the reaction to a standstill. `tb.settle().await?` does the same
for a reaction the test started some other way. A delay (`retry_after`) is tested on a paused
clock: `#[tokio::test(start_paused = true)]`, then `tb.advance(delay).await?`. On a running clock
the in-process `advance` panics.

```rust
#[tokio::test(start_paused = true)]
async fn a_failing_charge_lands_on_the_dead_letter() -> Result<(), Box<dyn Error>> {
    // `with_state` replaces what `on_startup` builds; the closure receives the app's own state type.
    let tb = TestApp::with_state(app(), |_| Shop { gateway: Gateway::failing() }).await?;
    tb.message(&Payment { id: 7 }).to("payments").publish().await?;
    let broker = tb.broker::<MemoryBroker>();
    broker
        .subscriber("payments")
        .assert_called_once()
        .settled(HandlerOutcome::retry_after(Duration::from_secs(60)));

    tb.advance(Duration::from_secs(60)).await?;
    tb.advance(Duration::from_secs(60)).await?;
    broker.subscriber("payments").assert_called(3);
    broker
        .published::<Payment>("payments.dead")
        .assert_called_once()
        .with(&Payment { id: 7 });
    Ok(())
}
```

### Replace state with `with_state`, not with a second builder

`TestApp::with_state(app(), |_| state)` starts the same app with a state the test built in place
of `on_startup`. Builder methods such as `app().state(..)` do not exist for this.

### Every harness call is fallible

`start`, `publish`, `settle` and `advance` return `Result`; the test returns
`Result<(), Box<dyn Error>>` and uses `?`.

## Quick reference

| Need | Call |
|---|---|
| Start | `TestApp::start(app()).await?`, `TestApp::with_state(app(), \|_\| state).await?` |
| Input | `broker.message(&v).to("name").publish().await?`; `tb.message(&v)` in a single-broker app; a type with a declared name needs no `.to(..)` |
| Headers | `broker.publish_with_headers("name", &v, &meta).await?`; `.with_headers(&meta)` on the input builder only for a type declaring `#[outgoing(headers = Meta)]` |
| Handler calls | `.assert_called_once()`, `.assert_called(n)`, `.assert_not_called()` |
| What it got | `.with(&v)`, `.received::<T>()`, `.batches::<T>()`, `.with_value(&v)` for a value the delivery already held |
| How it settled | `.settled(HandlerOutcome::ack())`, `.outcomes()`, `.panicked()`; `.assert_last_failed_to_decode()` ends the chain (a payload or a `Headers<T>` contract that failed) |
| Published | `broker.published::<T>("name")`, `.with(&v)`, `.with_header(..)`, `.with_options(&opts)`, `.assert_options_default()` |
| A slot | `tb.out::<Marker>()`, then `.decoded_as::<T>()` |
| Time | `#[tokio::test(start_paused = true)]` and `tb.advance(d).await?`; `tb.drain().await` for `and_after` work |
| A real broker | `TestApp::start_live(app())`: the same body against a running stand |

Every function has its own page under
<https://powersemmi.github.io/ruststream/latest/components/application/testing/>, and the
[testing module](https://docs.rs/ruststream/latest/ruststream/testing/index.html) on docs.rs is
the API reference.
Files in this package (2)
  • SKILL.md 8 KB
  • agents/openai.yml 1 KB

Versions

The database has no other skills named ruststream-testing.

Database snapshot: 13.11.2026 · package version ebc315d1862a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ruststream-broker
    Use when writing, changing or debugging a RustStream broker crate, the adapter between `ruststream` and a broker client: the connect and shutdown lifecycle, publishers and per-message options, subscriptions and retry copies, batching and other capabilities, the crate prelude,…
  • 100ruststream
    Use when writing, changing or debugging a service built on the RustStream messaging framework (crates `ruststream` and `ruststream-*` broker crates such as nats, rdkafka, lapin, fred): subscriber handlers, the app, replies and publishing, acks, retries and dead letters, state,…
  • 96testing
    Use when writing, changing, or reviewing tests, or when fixing a bug.
  • 100go-testing
    Write and run Go tests using the built-in testing package with table-driven tests, subtests, and mocking via interfaces. Use when writing Go tests or setting up test infrastructure.
  • 100pact-contract-testing-configuration
    Sets up consumer-driven contract testing with Pact — writing consumer contract tests that generate a pact file, standing up and configuring a Pact Broker (or PactFlow) to publish and share contracts, and writing provider verification tests against the broker's published pacts.…
  • 95swift-testing
    Write and migrate tests using the Swift Testing framework with @Test, @Suite, #expect, #require, confirmation, parameterized tests, test tags, traits, withKnownIssue, XCTest UI testing, XCUITest, test plan, mocking, test doubles, testable architecture, snapshot testing, async…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.