# awa-testing
Test utilities for the [Awa](https://crates.io/crates/awa) job queue.
`awa-testing` lets you exercise job handlers and admin code paths in
unit and integration tests without spinning up the full worker
runtime. Use it for in-tree tests of the workspace, in your own
crate's tests, or anywhere you want to drive a single job through a
real Postgres without configuring queues, dispatchers, and
maintenance leaders.
The crate is `dev-dependencies`-shaped: there is no embedded Postgres,
you point it at a real test database (typically a local container on
port `15432`).
## What's in here
- `TestClient` — synchronous-feeling wrapper around a `PgPool`:
- `migrate()` runs the schema and resets the runtime backend so
tests start from a known state.
- `clean()` truncates `awa.jobs`, `awa.queue_meta`, and the
runtime-storage backend rows for cross-test isolation.
- `insert(&args)` enqueues one job.
- `work_one(&worker)` / `work_one_in_queue(&worker, queue)` claim
and execute exactly one job through the supplied `Worker`,
returning a `WorkResult` (`Completed`, `Failed`, `Snoozed`,
`Cancelled`, `WaitingExternal`, `NoJob`).
- `get_job(id)` returns the current `JobRow`.
- `WorkResult` — enum with `is_completed()`, `is_failed()`,
`is_waiting_external()`, `is_no_job()` predicates.
- `setup` module — `database_url()`, `database_url_with_app_name()`,
`pool()`, `pool_with_url()` helpers and `reset_runtime_backend()`
for explicit test cleanup.
## Usage
```rust
use awa::JobArgs;
use awa_testing::TestClient;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, JobArgs)]
struct SendEmail {
to: String,
subject: String,
}
struct SendEmailWorker;
#[async_trait::async_trait]
impl awa::Worker for SendEmailWorker {
type Args = SendEmail;
fn kind(&self) -> &'static str { "send_email" }
async fn perform(&self, ctx: &awa::JobContext<Self::Args>) -> awa::JobResult {
// ... run the side-effect under test ...
Ok(())
}
}
#[tokio::test]
async fn send_email_completes() {
let pool = awa_testing::setup::pool(4).await;
let client = TestClient::from_pool(pool).await;
client.migrate().await.unwrap();
client.insert(&SendEmail {
to: "test@example.com".into(),
subject: "Test".into(),
}).await.unwrap();
let result = client.work_one_in_queue(&SendEmailWorker, Some("default")).await.unwrap();
assert!(result.is_completed());
}
```
## See also
- [Test plan](../docs/test-plan.md)
- [Development](../docs/development.md)
- For Python projects, the equivalent helpers live in
[`awa.testing`](../awa-python/python/awa/testing.py).
## License
MIT OR Apache-2.0