This module simplifies testing workers and making assertions about enqueued jobs.

Assertions may be made on any property of a job, but you'll typically want to check by args, queue or worker. If you're using namespacing through PostgreSQL schemas, also called "prefixes" in Ecto, you should use the prefix option when doing assertions about enqueued jobs during testing. By default the prefix option is public.

Using in Tests

The most convenient way to use Oban.Testing is to use the module:

use Oban.Testing, repo: MyApp.Repo

That will define the helper functions you'll use to make assertions on the jobs that should (or should not) be inserted in the database while testing.

Along with the repo you can also specify an alternate prefix to use in all assertions:

use Oban.Testing, repo: MyApp.Repo, prefix: "business"

Some example assertions:

# Assert that a job was already enqueued
assert_enqueued worker: MyWorker, args: %{id: 1}

# Assert that a job was enqueued or will be enqueued in the next 100ms
assert_enqueued [worker: MyWorker, args: %{id: 1}], 100

# Refute that a job was already enqueued
refute_enqueued queue: "special", args: %{id: 2}

# Refute that a job was already enqueued or would be enqueued in the next 100ms
refute_enqueued queue: "special", args: %{id: 2}, 100

# Make assertions on a list of all jobs matching some options
assert [%{args: %{"id" => 1}}] = all_enqueued(worker: MyWorker)

# Assert that no jobs are enqueued in any queues
assert [] = all_enqueued()

Note that the final example, using all_enqueued/1, returns a raw list of matching jobs and does not make an assertion by itself. This makes it possible to test using pattern matching at the expense of being more verbose.

Example

Given a simple module that enqueues a job:

defmodule MyApp.Business do
  def work(args) do
    args
    |> Oban.Job.new(worker: MyApp.Worker, queue: :special)
    |> Oban.insert!()
  end
end

The behaviour can be exercised in your test code:

defmodule MyApp.BusinessTest do
  use ExUnit.Case, async: true
  use Oban.Testing, repo: MyApp.Repo

  alias MyApp.Business

  test "jobs are enqueued with provided arguments" do
    Business.work(%{id: 1, message: "Hello!"})

    assert_enqueued worker: MyApp.Worker, args: %{id: 1, message: "Hello!"}
  end
end

Matching Scheduled Jobs and Timestamps

In order to assert a job has been scheduled at a certain time, you will need to match against the scheduled_at attribute of the enqueued job.

in_an_hour = DateTime.add(DateTime.utc_now(), 3600, :second)
assert_enqueued worker: MyApp.Worker, scheduled_at: in_an_hour

By default, Oban will apply a 1 second delta to all timestamp fields of jobs, so that small deviations between the actual value and the expected one are ignored. You may configure this delta by passing a tuple of value and a delta option (in seconds) to corresponding keyword:

assert_enqueued worker: MyApp.Worker, scheduled_at: {in_an_hour, delta: 10}

Adding to Case Templates

To include helpers in all of your tests you can add it to your case template:

defmodule MyApp.DataCase do
  use ExUnit.CaseTemplate

  using do
    quote do
      use Oban.Testing, repo: MyApp.Repo

      import Ecto
      import Ecto.Changeset
      import Ecto.Query
      import MyApp.DataCase

      alias MyApp.Repo
    end
  end
end