Skip to content

std::jobs::testing

Testing code that uses std::jobs. Inline is a Queue kept in memory, and run_queued runs every due job in the test’s own task, so a test enqueues, runs and asserts with no database, worker or sleep:

test "a batch job emails each subscriber"
    queue = Inline.new()
    _ = jobs.enqueue(queue, Fake.new(), batch_job, BatchArgs{post_id: 7})?
    // The post has two subscribers, so batch_job enqueues two email jobs,
    // which run in the same call.
    ran = run_queued(queue, [batch_job, email_job])
    assert Iter.map(ran, &(&1.kind)) |> Iter.to_list() == ["batch", "email", "email"]
end

A test of a schedule steps it with jobs.enqueue_due(queue, schedule, at) at the instants it names, so it reads no clock, and counts the jobs Inline.jobs holds.

Inline ignores the Conn it is given, so a job enqueued in a transaction that rolls back is still stored. A test about rollback runs against a durable backend. conformance is the suite every backend passes: a backend’s own tests run it against queues it opens.

Import with import std::jobs::testing.

enum JobState
    Available
    Running
    Completed
    Discarded
end

Where a stored job stands.

impl Debug for JobState

fn inspect(value: JobState) -> String

impl Debug.inspect

impl Equatable for JobState

fn equal(a: JobState, b: JobState) -> Bool

impl Equatable.equal

struct JobError
    attempt: Int
    at: Instant
    error: String
end

One failed run of a stored job.

impl Debug for JobError

fn inspect(value: JobError) -> String

impl Debug.inspect

impl Equatable for JobError

fn equal(a: JobError, b: JobError) -> Bool

impl Equatable.equal

struct StoredJob
    id: JobId
    queue: String
    kind: String
    args: Json
    state: JobState
    attempt: Int
    max_attempts: Int
    priority: Int
    unique_key: Maybe<String>
    unique_across: UniqueStates
    run_at: Instant
    locked_by: Maybe<String>
    locked_until: Maybe<Instant>
    errors: List<JobError>
    finished_at: Maybe<Instant>
end

A job as Inline holds it.

impl Debug for StoredJob

fn inspect(value: StoredJob) -> String

impl Debug.inspect

impl Equatable for StoredJob

fn equal(a: StoredJob, b: StoredJob) -> Bool

impl Equatable.equal

struct Inline

opaque — construction surface is private to its defining module

A Queue kept in memory, shared by every copy of the value. It ignores the Conn an enqueue gives it, and wakes the workers watching it on each enqueue. A test usually runs its jobs with run_queued rather than a Worker.

queue = Inline.new()
job = Job.new("count", fn _: Int -> Ok(Unit))
assert Result.is_ok(jobs.enqueue(queue, Fake.new(), job, 3))
assert Iter.map(Inline.jobs(queue), &(&1.kind)) |> Iter.to_list() == ["count"]
fn new(retention: Duration = Duration.hours(24 * 7)) -> Inline

type function on Inline

An empty queue that keeps finished jobs for retention.

fn jobs(inline: Inline) -> List<StoredJob>

type function on Inline

Every job held, in the order they were enqueued.

impl Queue for Inline

fn insert(inline: Inline, conn: Conn, job: NewJob) -> Result<Enqueued, sql.Error>

impl Queue.insert

impl Queue for Inline

fn claim(inline: Inline, worker: String, queues: List<String>, kinds: List<String>, limit: Int, lease: Duration) -> Result<List<Claimed>, sql.Error>

impl Queue.claim

impl Queue for Inline

fn renew(inline: Inline, worker: String, job: Claimed, lease: Duration) -> Result<Bool, sql.Error>

impl Queue.renew

impl Queue for Inline

fn settle(inline: Inline, worker: String, job: Claimed, how: Settle) -> Result<Bool, sql.Error>

impl Queue.settle

impl Queue for Inline

fn release(inline: Inline, worker: String) -> Result<Int, sql.Error>

impl Queue.release

impl Queue for Inline

fn rescue(inline: Inline) -> Result<Int, sql.Error>

impl Queue.rescue

impl Queue for Inline

fn prune(inline: Inline) -> Result<Int, sql.Error>

impl Queue.prune

impl Queue for Inline

fn watch(inline: Inline, supervisor: Supervisor, wake: Sender<Unit>) -> Unit

impl Queue.watch

impl Queue for Inline

fn last_tick(inline: Inline, schedule: String) -> Result<Maybe<Instant>, sql.Error>

impl Queue.last_tick

impl Queue for Inline

fn record_tick(inline: Inline, schedule: String, tick: Instant, job: Maybe<NewJob>) -> Result<Maybe<Enqueued>, sql.Error>

impl Queue.record_tick

impl Debug for Inline

fn inspect(value: Inline) -> String

impl Debug.inspect

struct Ran
    id: JobId
    kind: String
    args: Json
    answer: Result<Unit, jobs.Failure>
end

One job run_queued ran: its id, kind and arguments, and what its handler returned.

impl Debug for Ran

fn inspect(value: Ran) -> String

impl Debug.inspect

impl Equatable for Ran

fn equal(a: Ran, b: Ran) -> Bool

impl Equatable.equal

fn run_queued(queue: Inline, handlers: List<Handler>) -> List<Ran>

Runs every due job of the kinds handlers handle, in the test’s own task, oldest first, and settles each as a worker would. A job a handler enqueues runs in the same call when it is due; a retried or snoozed job does not, since it is due later. Returns each job run, in order. Two handlers of one kind trap, where Worker.start returns an Err: a test fails at its line.

queue = Inline.new()

double = Job.new("double", fn n: Int ->
    if n > 0 then
        Ok(Unit)
    else
        Err(jobs.Failure.Discard("not positive"))
    end
end)

_ = jobs.enqueue(queue, Fake.new(), double, 2)
_ = jobs.enqueue(queue, Fake.new(), double, -1)
ran = run_queued(queue, [double])

assert Iter.map(ran, &(&1.answer)) |> Iter.to_list() == [
    Ok(Unit),
    Err(jobs.Failure.Discard("not positive")),
]

assert Iter.map(Inline.jobs(queue), &(&1.state)) |> Iter.to_list() == [
    JobState.Completed,
    JobState.Discarded,
]
fn decodes<A>(job: Job<A>, text: String) -> Result<A, String> where A: FromJson

Decodes text, a stored job’s arguments as JSON, as job’s argument type, or returns the decode error. A test keeps an old payload, copied out of a queue, decoding against the current type.

job = Job.new("count", fn _: Int -> Ok(Unit))
assert decodes(job, "3") == Ok(3)
assert Result.is_err(decodes(job, "\"three\""))
struct Opened
    queue: Queue
    conn: Conn
end

A queue and a connection to enqueue on, as conformance opens them.

impl Debug for Opened

fn inspect(value: Opened) -> String

impl Debug.inspect

struct Broken
    rule: String
    message: String
end

A conformance rule a backend broke, and how. Its Display is rule: message.

impl Display for Broken

fn to_string(broken: Broken) -> String

impl Display.to_string

impl Debug for Broken

fn inspect(value: Broken) -> String

impl Debug.inspect

impl Equatable for Broken

fn equal(a: Broken, b: Broken) -> Bool

impl Equatable.equal

fn conformance(transactional: Bool = True, open: () -> Result<Opened, sql.Error>) -> List<Broken>

Runs every conformance rule against queues from open, and returns the rules broken: none for a backend that conforms. Each rule opens a fresh queue on a fresh connection and enqueues jobs of the kinds conformance and conformance_other on it. transactional is False for a backend that ignores the Conn it is given, as Inline does, which skips the rule that a rolled-back enqueue stores no job.

The rules cover a committed enqueue being claimable with its kind, arguments and attempt, a rolled-back one storing nothing, run_at, oldest first, two claims never taking one job (also from two tasks at once), each way a job settles, a settle or renew by a worker that does not hold the job changing nothing, a rescued lease, a late settle after a rescue, a rescue on the last attempt, release freeing only its own worker’s jobs, the queue and kind filters, priorities, unique keys in each state and from two tasks at once, and recording ticks. transactional: False also skips the rule that a rolled-back unique enqueue frees its key.

assert conformance(transactional: False, fn ->
    Ok(Opened{queue: Inline.new(), conn: Fake.new()})
end) == []
fn rules() -> List<String>

The names of the conformance rules, in the order conformance runs them.

assert Iter.contains(rules(), "two claims never take one job")