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.
Exports
Section titled “Exports”enum JobState
Section titled “enum JobState”enum JobState Available Running Completed Discarded end
Where a stored job stands.
JobState.inspect
Section titled “JobState.inspect”impl Debug for JobState
fn inspect(value: JobState) -> String
impl Debug.inspect
JobState.equal
Section titled “JobState.equal”impl Equatable for JobState
fn equal(a: JobState, b: JobState) -> Bool
impl Equatable.equal
struct JobError
Section titled “struct JobError”struct JobError attempt: Int at: Instant error: String end
One failed run of a stored job.
JobError.inspect
Section titled “JobError.inspect”impl Debug for JobError
fn inspect(value: JobError) -> String
impl Debug.inspect
JobError.equal
Section titled “JobError.equal”impl Equatable for JobError
fn equal(a: JobError, b: JobError) -> Bool
impl Equatable.equal
struct StoredJob
Section titled “struct StoredJob”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.
StoredJob.inspect
Section titled “StoredJob.inspect”impl Debug for StoredJob
fn inspect(value: StoredJob) -> String
impl Debug.inspect
StoredJob.equal
Section titled “StoredJob.equal”impl Equatable for StoredJob
fn equal(a: StoredJob, b: StoredJob) -> Bool
impl Equatable.equal
struct Inline
Section titled “struct Inline”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"]
Inline.new
Section titled “Inline.new”fn new(retention: Duration = Duration.hours(24 * 7)) -> Inline
type function on Inline
An empty queue that keeps finished jobs for retention.
Inline.jobs
Section titled “Inline.jobs”fn jobs(inline: Inline) -> List<StoredJob>
type function on Inline
Every job held, in the order they were enqueued.
Inline.insert
Section titled “Inline.insert”impl Queue for Inline
fn insert(inline: Inline, conn: Conn, job: NewJob) -> Result<Enqueued, sql.Error>
impl Queue.insert
Inline.claim
Section titled “Inline.claim”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
Inline.renew
Section titled “Inline.renew”impl Queue for Inline
fn renew(inline: Inline, worker: String, job: Claimed, lease: Duration) -> Result<Bool, sql.Error>
impl Queue.renew
Inline.settle
Section titled “Inline.settle”impl Queue for Inline
fn settle(inline: Inline, worker: String, job: Claimed, how: Settle) -> Result<Bool, sql.Error>
impl Queue.settle
Inline.release
Section titled “Inline.release”impl Queue for Inline
fn release(inline: Inline, worker: String) -> Result<Int, sql.Error>
impl Queue.release
Inline.rescue
Section titled “Inline.rescue”impl Queue for Inline
fn rescue(inline: Inline) -> Result<Int, sql.Error>
impl Queue.rescue
Inline.prune
Section titled “Inline.prune”impl Queue for Inline
fn prune(inline: Inline) -> Result<Int, sql.Error>
impl Queue.prune
Inline.watch
Section titled “Inline.watch”impl Queue for Inline
fn watch(inline: Inline, supervisor: Supervisor, wake: Sender<Unit>) -> Unit
impl Queue.watch
Inline.last_tick
Section titled “Inline.last_tick”impl Queue for Inline
fn last_tick(inline: Inline, schedule: String) -> Result<Maybe<Instant>, sql.Error>
impl Queue.last_tick
Inline.record_tick
Section titled “Inline.record_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
Inline.inspect
Section titled “Inline.inspect”impl Debug for Inline
fn inspect(value: Inline) -> String
impl Debug.inspect
struct Ran
Section titled “struct Ran”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.
Ran.inspect
Section titled “Ran.inspect”impl Debug for Ran
fn inspect(value: Ran) -> String
impl Debug.inspect
Ran.equal
Section titled “Ran.equal”impl Equatable for Ran
fn equal(a: Ran, b: Ran) -> Bool
impl Equatable.equal
testing.run_queued
Section titled “testing.run_queued”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,
]
testing.decodes
Section titled “testing.decodes”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
Section titled “struct Opened”struct Opened queue: Queue conn: Conn end
A queue and a connection to enqueue on, as conformance opens them.
Opened.inspect
Section titled “Opened.inspect”impl Debug for Opened
fn inspect(value: Opened) -> String
impl Debug.inspect
struct Broken
Section titled “struct Broken”struct Broken rule: String message: String end
A conformance rule a backend broke, and how. Its Display is rule: message.
Broken.to_string
Section titled “Broken.to_string”impl Display for Broken
fn to_string(broken: Broken) -> String
impl Display.to_string
Broken.inspect
Section titled “Broken.inspect”impl Debug for Broken
fn inspect(value: Broken) -> String
impl Debug.inspect
Broken.equal
Section titled “Broken.equal”impl Equatable for Broken
fn equal(a: Broken, b: Broken) -> Bool
impl Equatable.equal
testing.conformance
Section titled “testing.conformance”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) == []
testing.rules
Section titled “testing.rules”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")