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:

runJob
runJobs
listJobs
listJobStatuses

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.


import {  } from "sidetrack";
 
const  = new <{
  : { : string };
}>({
  : {
    : .["DATABASE_URL"]!,
  },
  : {
    : {
      : async (, ) => {
        .("ran job");
      },
    },
  },
});


// You can run jobs on a single queue
await .({ : "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 .({ : "userOnboarding", : 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 .("userOnboarding", { : "a@example.com" });
await .("userOnboarding", { : "b@example.com" });
 
// You can run jobs on a single queue
const  = await .({ : "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  = await .("userOnboarding", {
  : "a@example.com",
});
await .("userOnboarding", { : "b@example.com" });
await .(.);
 
// since we only ran job 1
// we should expect 1 job to be completed, 1 job to be in scheduled
const  = await .({ : "userOnboarding" });
// expect(jobs).toBeObject({ scheduled: 1, completed: 1 });