Skip to content
Testing

Testing

bikesched-test removes the boilerplate every test of a bikesched-based application repeats: a uniquely-named test node and polling for a job to reach an expected state.

DataSource dataSource = ...; // the application's own test database

try (Bikesched bikesched = BikeschedTest.testNode(dataSource).jsonMapper(new JacksonJsonMapper()).build()) {
    bikesched.registerJobHandler("send-mail", job -> mailer.send(job.payload()));
    UUID jobId = bikesched.newJob("send-mail").payload(mail).schedule();

    JobInfo job = BikeschedTest.awaitJob(bikesched, jobId).untilSucceeded();
}

The module never starts, resets or migrates a database itself: the caller supplies the DataSource, e.g. a Testcontainers PostgreSQL shared across a test class, exactly as the examples do.

Test nodes

BikeschedTest.testNode(dataSource) (or testNode(dataSource, nodeNamePrefix)) returns a BikeschedBuilder with test-friendly defaults:

  • a node name unique to the call, <nodeNamePrefix>-<random UUID> ("test-…" without a prefix), so tests run in parallel without clashing node names;
  • a poll interval of 50 ms, so a job scheduled “now” is claimed promptly.

Every other option (JSON mapper, heartbeat interval, concurrency, listeners, history, …) is set on the returned builder like on any other Bikesched.builder(dataSource). The caller still calls build() and closes the node, e.g. in a try-with-resources block or an @AfterEach method.

Waiting for a job

BikeschedTest.awaitJob(bikesched, jobId) returns a JobAwait that polls the node (every 50 ms, up to a 10 second default timeout) until the job reaches the awaited outcome, then returns the result read at that point; it throws org.awaitility.core.ConditionTimeoutException if the timeout passes first.

Method Waits until Returns
timeout(Duration) — (overrides the default timeout) this JobAwait, for chaining
untilEnded() the job’s state satisfies JobState.isEnded() the job
untilState(JobState... states) the job is in one of the given states the job
untilSucceeded() like untilState(JobState.SUCCEEDED) the job
untilSucceededSteps(String... names) the job’s succeeded steps, in the order they started, are exactly the given names the succeeded steps

JobAwait is backed by Awaitility internally, but Awaitility itself is never part of this module’s API; a test that needs its full API (e.g. a custom condition) adds the awaitility dependency itself, like the examples already do for anything JobAwait does not cover.

Skipping time

Postgres decides with now() when a job or a waiting step is due, so a test cannot skip a sleep, a retry backoff or a recurring job’s interval with a fake Clock. Instead, bikesched-test moves the stored times of pending jobs back, which has the same effect for those jobs:

bikesched.registerJobHandler("onboarding", job -> {
    job.sleep("wait-a-day", Duration.ofDays(1));
    job.step("send-reminder", () -> mailer.sendReminder(job.payload()));
});
UUID jobId = bikesched.newJob("onboarding").payload(user).schedule();
BikeschedTest.awaitJob(bikesched, jobId).untilState(JobState.WAITING);

BikeschedTest.fastForward(dataSource, jobId); // the day is over

BikeschedTest.awaitJob(bikesched, jobId).untilSucceeded();
Method Effect Returns
fastForward(DataSource, UUID jobId) skips the job ahead to its next due time, so it runs now: a sleep ends, a poll checks again, a retry or a delayed job starts, a recurring occurrence runs, and a wait whose timeout is that due time times out (a poll checks once more first) false if the job is running, has ended, does not exist, or waits without a timeout
advanceTime(DataSource, Duration, String name, String... moreNames) advances the pending jobs with the given names by the duration: whatever was due within it runs now, the rest keeps waiting, closer by the duration the number of jobs moved
advanceTime(DataSource, Duration, TypedJob<?> typedJob, TypedJob<?>... moreTypedJobs) the same for typed jobs the number of jobs moved

Both move a job’s scheduled_at (and the planned run of an occurrence) and the wake-up times and poll deadlines of its waiting steps back by the same amount, so a job’s later deadlines keep their distance. They then notify the listening nodes, so the jobs now due are claimed at once. Only pending jobs are moved: running and ended jobs, events (and their retention) and the clean-up of old rows are not affected, and time never moves backward. A recurring job’s next occurrence is computed from the real time again once a moved occurrence ran. Scoping by job id or job name keeps tests running in parallel on one database apart.

Non-goals

bikesched-test does not own a database (no Testcontainers dependency), does not manage the node’s lifecycle beyond returning a configured builder, and has no JUnit extension, AssertJ assertions or Spring Boot-specific helper for now; any of these may be added later once repeated boilerplate in real applications justifies the extra dependency.