Introduction to Testing

Oban Pro provides advanced helpers that make it easy to test workers, drain queues reliably, supervise test instances, and make assertions about enqeueud jobs. These are the exact same helpers that Pro uses for testing internally!

Configure for Testing

Testing Pro features such as Batch and Workflow workers only works when testing in :manual mode. If you're running with :inline mode, or don't have testing configured at all, update your test config:

# test.exs
config :my_app, Oban, testing: :manual

Now you're ready to import the advanced test helpers.

Setup Testing Helpers

All testing helpers are provided by Oban.Pro.Testing, a drop-in replacement for Oban.Testing with additional functions tailored toward integration testing and Pro modules.

The most convenient way to use the helpers is to use the module within your test case:

defmodule MyApp.Case do
  use ExUnit.CaseTemplate

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

Alternatively, you can use the testing module in individual tests if you'd prefer not to include helpers in every test.

defmodule MyApp.WorkerTest do
  use MyApp.Case, async: true

  use Oban.Pro.Testing, repo: MyApp.Repo
end

Using Oban.Pro.Testing requires the repo option because it's injected into many of the generated helpers. Other repo-specific options like prefix and log are also supported:

using do
  quote do
    use Oban.Pro.Testing, repo: MyApp.Repo, prefix: "private", log: :debug
  end
end

See the Oban.Pro.Testing docs for complete options and usage.

Understanding the Types of Helpers

Much like the layers of a traditional testing pyramid, Oban.Pro.Testing stratifies into unit, integration, and acceptance helpers:

• Unit—execute jobs locally, without touching the database. These helpers start with a perform_ prefix, e.g. perform_job or perform_callback.

• Integration—insert jobs into the database and execute them inline. These helpers start with drain_ or run_, e.g. drain_jobs or run_workflow.

• Acceptance—run Oban as a supervised process that autonomously runs queues and plugins normally. This is simplified with the start_supervised_oban! helper.

Each layer of testing has its place within a complex application's test suite. Let's start with unit testing in Testing Pro Workers.