awa-testing

Test utilities for the 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

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
• Development
• For Python projects, the equivalent helpers live in awa.testing.

License

MIT OR Apache-2.0