Testing Sidetrack
Sidetrack provides multiple test utilities function under the SidetrackTest class.
The SidetrackTest class extends all the functions under Sidetrack, but also exposes these helpful utils:
runJobrunJobslistJobslistJobStatuses
Here’s some common scenarios when testing your background jobs.
Running a job
In your tests, if you don’t run sidetrack.start(), then Sidetrack won’t poll your database for new jobs.
You can manually run a job with the runJob function.
import { } from "sidetrack";
import { , } from "vitest";
("job runs", async () => {
const = new <{
: { : string };
}>({
: {
: .["DATABASE_URL"]!,
},
: {
: {
: async () => {
.("ran job");
},
},
},
});
const = await .("userOnboarding", {
: "a@example.com",
});
// this job stays in scheduled and won't be run because we haven't run sidetrack.start()
((await .(.)).).("scheduled");
// You decide when to run the job
await .(.);
((await .(.)).).("completed");
});Running jobs in a queue
While runJob only allows you to run a single job, often you may want to run all the jobs on a queue.
// You can run jobs on a single queue
await sidetrack.runJobs({ queue: "userOnboarding" });By default, runJobs runs jobs that are scheduled in the past or present. If you want to include future jobs you may pass an option for {includeFutureJobs: true}
// Will run all jobs on this queue, including ones with scheduledAt in the future
await sidetrack.runJobs(
{ queue: "userOnboarding" },
{ includeFutureJobs: true },
);Listing jobs
You may want to assert that certain jobs exist on a queue(s).
listJob accepts a single queue or list of queues, and returns a list of jobs.
await sidetrack.insert("userOnboarding", { email: "a@example.com" });
await sidetrack.insert("userOnboarding", { email: "b@example.com" });
// You can run jobs on a single queue
const jobs = await sidetrack.listJobs({ queue: "userOnboarding" });
expect(jobs.length).toBe(2);Listing job statuses
listJobStatuses provides a convenient way to know the breakdown of all the jobs and their statuses.
const job1 = await sidetrack.insert("userOnboarding", {
email: "a@example.com",
});
await sidetrack.insert("userOnboarding", { email: "b@example.com" });
await sidetrack.runJob(job1.id);
// since we only ran job 1
// we should expect 1 job to be completed, 1 job to be in scheduled
const jobs = await sidetrack.listJobsStatuses("userOnboarding");
expect(jobs).toBeObject({ scheduled: 1, completed: 1 });