Oban v1.1.0 Oban.Testing View Source

This module simplifies making assertions about enqueued jobs during testing.

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 three helper functions, assert_enqueued/1, refute_enqueued/1 and all_enqueued/1. The functions can then be used to make assertions on the jobs that have been inserted in the database while testing.

assert_enqueued worker: MyWorker, args: %{id: 1}

# or

refute_enqueued queue: "special", args: %{id: 2}

# or

assert [%{args: %{"id" => 1}}] = all_enqueued(worker: MyWorker)

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 general

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

Link to this section Summary

Functions

Retrieve all currently enqueued jobs matching a set of options.

Assert that a job with particular options has been enqueued.

Refute that a job with particular options has been enqueued.

Link to this section Functions

Link to this function

all_enqueued(repo, opts)

View Source (since 0.6.0)
all_enqueued(repo :: module(), opts :: Keyword.t()) :: [Oban.Job.t()]

Retrieve all currently enqueued jobs matching a set of options.

Only jobs matching all of the provided arguments will be returned. Additionally, jobs are returned in descending order where the most recently enqueued job will be listed first.

Examples

Assert based on only some of a job's args:

assert [%{args: %{"id" => 1}}] = all_enqueued(worker: MyWorker)

Assert that exactly one job was inserted for a queue:

assert [%Oban.Job{}] = all_enqueued(queue: :alpha)
Link to this function

assert_enqueued(repo, opts)

View Source (since 0.3.0)
assert_enqueued(repo :: module(), opts :: Keyword.t()) :: true

Assert that a job with particular options has been enqueued.

Only values for the provided arguments will be checked. For example, an assertion made on worker: "MyWorker" will match any jobs for that worker, regardless of the queue or args.

Link to this function

refute_enqueued(repo, opts)

View Source (since 0.3.0)
refute_enqueued(repo :: module(), opts :: Keyword.t()) :: false

Refute that a job with particular options has been enqueued.

See assert_enqueued/2 for additional details.