Struct TestApp 

pub struct TestApp { /* private fields */ }

Builder for constructing a fully-configured Autumn application in tests.

Analogous to Spring Boot’s @SpringBootTest – it wires up routes, middleware, config, and optionally a database pool, then produces a TestClient ready to fire requests.

Examples

use autumn_web::prelude::*;
use autumn_web::test::TestApp;

#[get("/ping")]
async fn ping() -> &'static str { "pong" }

#[tokio::test]
async fn ping_works() {
    let client = TestApp::new()
        .routes(routes![ping])
        .build();

    client.get("/ping").send().await.assert_ok();
}

Implementations

impl TestApp

pub fn new() -> Self

Create a new test app builder with default configuration.

pub fn policy<R, P>(self, policy: P) -> Self

where R: Send + Sync + 'static, P: Policy<R>,

Register a Policy for resource type R. Mirrors AppBuilder::policy.

pub fn scope<R, S>(self, scope: S) -> Self

where R: Send + Sync + 'static, S: Scope<R>,

Register a Scope for resource type R. Mirrors AppBuilder::scope.

pub const fn forbidden_response(self, value: ForbiddenResponse) -> Self

Override the deny-response shape used by #[authorize] and #[repository(policy = ...)] handlers. Useful for round-tripping the 403-vs-404 decision in tests.

pub fn openapi(self, config: OpenApiConfig) -> Self

Enable OpenAPI spec generation for the test app.

Mirrors crate::app::AppBuilder::openapi so integration tests can exercise the /openapi.json and /swagger-ui endpoints.

Gated behind the openapi Cargo feature.

pub fn mount_mcp(self, path: impl Into<String>) -> Self

Mount an MCP endpoint at path, mirroring AppBuilder::mount_mcp so integration tests can drive initialize/tools/list/tools/call through the in-process pipeline.

Gated behind the mcp Cargo feature.

pub fn expose_all_as_mcp(self) -> Self

Enable the whole-API MCP hatch, mirroring AppBuilder::expose_all_as_mcp.

Gated behind the mcp Cargo feature.

pub fn secure_mcp<L>(self, layer: L) -> Self

where L: Layer<Route> + Clone + Send + Sync + 'static, L::Service: Service<Request<Body>, Response = Response<Body>, Error = Infallible> + Clone + Send + Sync + 'static, <L::Service as Service<Request<Body>>>::Future: Send + 'static,

Gate the entire MCP endpoint behind a tower layer, mirroring AppBuilder::secure_mcp.

Gated behind the mcp Cargo feature.

pub fn mcp_tasks(self, config: McpTaskConfig) -> Self

Set the limits for MCP task tools, mirroring AppBuilder::mcp_tasks.

Gated behind the mcp Cargo feature.

pub fn mcp_instructions(self, text: impl Into<String>) -> Self

Set the MCP server instructions, mirroring AppBuilder::mcp_instructions.

Gated behind the mcp Cargo feature.

pub fn mcp_catalog(self, catalog: McpCatalog) -> Self

Select the MCP tool catalog, mirroring AppBuilder::mcp_catalog.

Gated behind the mcp Cargo feature.

pub fn merge(self, router: Router<AppState>) -> Self

Merge a router into the internal application state.

This is useful when testing modular route definitions without building the full application.

pub fn scoped<L>(self, prefix: &str, layer: L, routes: Vec<Route>) -> Self

where L: Layer<Route> + Clone + Send + Sync + 'static, L::Service: Service<Request<Body>, Response = Response<Body>, Error = Infallible> + Clone + Send + Sync + 'static, <L::Service as Service<Request<Body>>>::Future: Send + 'static,

Mount routes under a scoped prefix with a route-local layer.

pub fn nest(self, path: &str, router: Router<AppState>) -> Self

Nest a router under a specific path prefix for testing.

This is useful for testing sub-applications or API versions.

pub fn layer<L: IntoAppLayer>(self, layer: L) -> Self

Apply a custom tower::Layer to the entire test application.

Mirrors crate::app::AppBuilder::layer so tests can exercise the exact middleware wiring that AppBuilder::run() produces.

pub fn static_gate<L: IntoAppLayer>(self, layer: L) -> Self

Register a pre-static gate layer for this test application.

Mirrors crate::app::AppBuilder::static_gate: the layer runs outermost (outside session and before the static cache lookup) so tests can exercise auth-gating wiring that protects cached SSG/ISG pages.

pub fn with_error_reporter<R: ErrorReporter>(self, reporter: R) -> Self

Register an ErrorReporter for this test app.

Mirrors crate::app::AppBuilder::with_error_reporter. Call multiple times to chain reporters; each receives every panic + 5xx event.

pub const fn idempotent(self) -> Self

Enable HTTP idempotency-key middleware for this test app.

Mirrors crate::app::AppBuilder::idempotent: sets the config.idempotency.enabled flag so that the router wires up the layer with the same MemoryIdempotencyStore and MetricsCollector that production uses.

pub fn from_router(router: Router, state: AppState) -> TestClient

Construct a TestClient directly from an axum::Router.

Useful for bypassing TestApp builder if you just want to write requests against a standard axum Router. The probe state returned by TestClient::probes will be in the default ready state; it is not connected to any handler in the supplied router.

Note: TestClient::sent_mail will always return an empty list for clients built this way. The built-in mail recorder is wired in during TestApp::build; because from_router receives an already-constructed AppState (with the mailer already installed), the recorder cannot be injected into its interceptor chain. Use TestApp::new().merge(router).build() to get recording support.

pub fn routes(self, routes: Vec<Route>) -> Self

Register a collection of routes to be built into the TestApp.

pub fn state_initializer<F>(self, f: F) -> Self

where F: FnOnce(&AppState) + Send + 'static,

Register a callback to configure/initialize the application state before building the router.

pub fn with_live_state<T>(self, initial: T) -> Self

where T: LiveState,

Install a designated live-state block, so handlers that read it through AppState::live_state can be tested.

Mirrors crate::app::AppBuilder::with_live_state. A test app never adopts a snapshot from a predecessor — there is no upgrade in flight — so initial is always the value handlers see.

pub fn with_flag_store<S>(self, store: S) -> Self

where S: FlagStore,

Register a FlagStore backend so the Flags extractor works in test handlers.

Mirrors crate::app::AppBuilder::with_flag_store.

pub fn with_flag_service(self, service: FeatureFlagService) -> Self

Mirrors crate::app::AppBuilder::with_flag_service. The build preloads the store before the first request.

pub fn with_notification_store<S>(self, store: S) -> Self

where S: NotificationStore,

Mirrors crate::app::AppBuilder::with_notification_store.

pub fn with_push_subscription_store<S>(self, store: S) -> Self

where S: PushSubscriptionStore,

Mirrors crate::app::AppBuilder::with_push_subscription_store.

pub fn with_web_push(self, push: WebPush) -> Self

Register an explicit WebPush service, overriding key, store and transport at once.

The usual reason is a RecordingPushTransport, so a test can assert exactly what would have gone to the push service.

pub fn plugin<P: Plugin>(self, plugin: P) -> Self

Apply a plugin directly to the test app.

pub fn with_mail_interceptor(self, interceptor: impl MailInterceptor) -> Self

pub fn with_suppression_store( self, store: impl SuppressionStore + 'static, ) -> Self

Register a SuppressionStore so List-Unsubscribe sends skip suppressed recipients and the unsubscribe endpoint records opt-outs. Mirrors AppBuilder::with_suppression_store.

pub fn with_mail_suppression_store( self, store: impl SuppressionStore + 'static, ) -> Self

Register a bounce/complaint SuppressionStore so Mailer::send skips hard-bounced/complained addresses under TestApp exactly as it does under AppBuilder::run. Mirrors AppBuilder::with_mail_suppression_store.

pub const fn mount_unsubscribe_endpoint(self) -> Self

Mount the framework’s default one-click unsubscribe endpoint (opt-in). Mirrors AppBuilder::mount_unsubscribe_endpoint.

pub fn with_job_interceptor(self, interceptor: impl JobInterceptor) -> Self

pub fn with_fault_plan(self, plan: FaultPlan) -> Self

Attach an authored, seed-deterministic fault schedule (FaultPlan, issue #1680).

The plan’s faults are injected through the existing interceptor seams, so no application code changes: the ordinal-th database checkout or job execution fails, exactly as a real transient failure would, and everything the run did is recorded into a serializable FaultOutcome reachable through TestClient::fault_outcome (or TestClient::fault_ledger).

It composes with, and never replaces, the interceptors already in play: the always-on enqueue recorder still records, a with_job_interceptor still runs (and observes the injected error like a real handler failure), transactional database isolation is preserved, and Sim::chaos keeps working alongside. The fault decision is innermost of each chain.

Attaching a plan registers an error reporter of its own, which — exactly like with_error_reporter — means the built-in LogReporter fallback is no longer installed for that app.

use autumn_web::sim::FaultPlan;

let client = TestApp::new()
    .plugin(ChargeCardJobs) // the plugin registering `charge_card`
    .with_fault_plan(FaultPlan::from_seed(0x5EED).fail_job("charge_card", 1))
    .build();

Determinism

Attaching a plan also defaults the app’s entropy source to SeededEntropy::shared(plan.seed()) when the test supplied none, so request ids and job-retry jitter replay from the same seed. Run the scenario under #[sim_test] (a paused, single-threaded runtime with a virtual clock) for the ordinals to be reproducible; see the fault module docs.

Panics

build panics if the config would make the fault schedule non-reproducible: more than one job worker (jobs.workers), error reporting disabled / sampled below 1.0 (the sampler draws OS randomness, so a sampled-out 5xx would be missing from the outcome at random), or failure capture enabled (reporting awaits the capsule’s blocking persistence before any reporter runs, so an observed 5xx could still be in flight when the outcome is read).

pub fn jobs(self, jobs: Vec<JobInfo>) -> Self

Register background jobs with the test app.

Collect them with jobs![..], exactly as in AppBuilder::jobs. They run under the in-process test job runtime that build starts.

pub fn tasks(self, tasks: Vec<TaskInfo>) -> Self

Register #[scheduled] tasks with the test app.

Collect them with tasks![..], exactly as in AppBuilder::tasks. build starts them on the in-process scheduler, and dropping the TestClient stops them. Their timers are tokio timers and they read the injected clock, so under a #[sim_test] a tick fires when crate::sim::Sim::advance crosses its deadline.

pub fn listeners(self, listeners: Vec<ListenerInfo>) -> Self

Register event listeners with the test app.

Collect them with listeners![..], exactly as in AppBuilder::listeners. Durable listeners run under the in-process test job runtime; sync listeners run in-request. Published events are always recorded, so TestClient::assert_event_published works without standing up jobs.

pub const fn with_outbox(self, config: OutboxConfig) -> Self

Enable the outbox relay with config (it sets enabled = true).

build cannot create the tables. Call crate::outbox::ensure_schema in the test first.

pub fn outbox_handler<F, Fut>( self, topic: impl Into<String>, handler: F, ) -> Self

where F: Fn(AppState, OutboxMessage) -> Fut + Send + Sync + 'static, Fut: Future<Output = AutumnResult<()>> + Send + 'static,

Set the outbox handler of topic, as AppBuilder::outbox_handler.

The test app runs no relay worker. Drain the outbox with crate::outbox::drain or crate::sim::Sim::run_to_idle. Set outbox.enabled = true in the config, and create the tables with crate::outbox::ensure_schema.

Panics

Panics when topic is empty or starts with autumn..

pub fn with_db_interceptor( self, interceptor: impl DbConnectionInterceptor, ) -> Self

pub fn with_channels_interceptor( self, interceptor: impl ChannelsInterceptor, ) -> Self

pub fn record_broadcasts(self) -> Self

Opt in to recording every channel broadcast published while requests run, enabling TestClient::broadcasts, TestClient::broadcasts_on, and the assert_broadcast* helpers.

No interceptor is installed — and channel publishing is untouched — unless this is called. Composes with a user-supplied with_channels_interceptor: the recorder runs first, then the user’s interceptor.

pub fn with_http_interceptor(self, interceptor: impl HttpInterceptor) -> Self

pub fn config(self, config: AutumnConfig) -> Self

Override the default test configuration.

pub fn profile(self, profile: &str) -> Self

Set the active profile (default is "test").

pub fn with_clock<C>(self, clock: C) -> Self

where C: ClockSource + 'static,

Inject a custom clock into the test app.

All handlers that take a crate::time::Clock extractor will see time as reported by clock. Use crate::time::FixedClock to pin time to a known instant, or crate::time::TickingClock when you need to step the clock forward between requests via TestClient::advance_clock.

use autumn_web::test::TestApp;
use autumn_web::time::{FixedClock, TickingClock};
use chrono::{TimeZone, Utc};

// Pin to a fixed instant:
let _client = TestApp::new()
    .with_clock(FixedClock::at(Utc.with_ymd_and_hms(2025, 1, 1, 0, 0, 0).unwrap()))
    .build();

// Step forward in time:
let clock = TickingClock::starting_at(Utc.with_ymd_and_hms(2025, 1, 1, 0, 0, 0).unwrap());
let client = TestApp::new()
    .with_clock(clock.clone())
    .build();
client.advance_clock(std::time::Duration::from_secs(3600));

pub fn with_entropy<E>(self, entropy: E) -> Self

where E: Entropy + 'static,

Inject a custom entropy source into the test app.

All handlers that take a crate::entropy::Rng extractor — and every framework-minted identifier (request ids, session ids, idempotency lock owners, job ids) — draw from entropy. Pass a crate::entropy::SeededEntropy to make the whole app’s identifier stream byte-for-byte reproducible under a fixed seed. Mirrors Self::with_clock.

use autumn_web::entropy::SeededEntropy;
use autumn_web::test::TestApp;

let _client = TestApp::new()
    .with_entropy(SeededEntropy::new(0x5eed))
    .build();

pub fn api_version(self, version: ApiVersion) -> Self

Register a single API version for testing.

pub fn agent_skill(self, skill: AgentSkill) -> Self

Publish an agent skill, as AppBuilder::agent_skill.

pub fn ucp_profile(self, profile: UcpProfile) -> Self

Serve a UCP profile, as AppBuilder::ucp_profile.

pub fn acp_discovery(self, document: AcpDiscovery) -> Self

Serve an ACP document, as AppBuilder::acp_discovery.

pub fn api_versions( self, versions: impl IntoIterator<Item = ApiVersion>, ) -> Self

Register multiple API versions for testing.

pub fn with_db(self, pool: Pool<RuntimeConnection>) -> Self

Attach a database connection pool to the test app.

pub const fn transactional(self) -> Self

Enable transactional test isolation using the database URL configured in the application’s configuration.

pub fn with_transactional_db(self, url: impl Into<String>) -> Self

Enable transactional test isolation with an explicit database URL.

pub fn with_shards(self, shards: Vec<ShardConfig>) -> Self

Configure the application’s horizontal shards programmatically, as if they were declared via [[database.shards]] in autumn.toml.

This is the escape hatch for tests that spin up shard databases at runtime (e.g. one Postgres container per shard) and need to point the app at them without writing a config file. Combine with transactional to get rolled-back shard writes.

use autumn_web::test::TestApp;
use autumn_web::config::ShardConfig;

let client = TestApp::new()
    .with_transactional_db("postgres://localhost/control")
    .with_shards(vec![
        ShardConfig { name: "shard0".into(), primary_url: shard0, ..Default::default() },
        ShardConfig { name: "shard1".into(), primary_url: shard1, ..Default::default() },
    ])
    .build();

pub fn http_mock(&mut self, alias: &str) -> MockSetupBuilder

Register a canned HTTP response for outbound requests made via the Client extractor during this test.

alias identifies the named service (must match the alias passed to Client::named in the handler, or the key used in [http.client.base_urls]).

Returns a MockSetupBuilder on which you chain the HTTP method and path before calling respond_with to register the entry and get a MockHandle for later assertions.

Examples

use autumn_web::test::TestApp;
use serde_json::json;

let mut app = TestApp::new();
let mock = app
    .http_mock("stripe")
    .post("/v1/charges")
    .respond_with(200, json!({"id": "ch_123", "amount": 1000}));

let client = app.build();
// … fire requests …
mock.expect_called(1);

pub fn build(self) -> TestClient

Build the application and return a TestClient ready for requests.

This constructs the full Axum router with all middleware applied, identical to what AppBuilder::run() produces – without binding a TCP listener.

The process-level global cache is cleared unconditionally so that #[cached] functions inside this test app always use their per-function Moka stores and do not accidentally inherit a Redis or other shared backend installed by a previous test.

Trait Implementations

impl Default for TestApp

fn default() -> Self

Returns the “default value” for a type.