Skip to content
Skills Library
Programming · Testing

testing-essentials

/testing-essentials

Use when writing or fixing ExUnit tests — DataCase/ConnCase, generated fixtures and scopes, LiveView test helpers, uploads, Mox and Req.Test stubs, async and sandbox rules.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
1
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when writing or fixing ExUnit tests — DataCase/ConnCase, generated fixtures and scopes, LiveView test helpers, uploads, Mox and Req.Test stubs, async and sandbox rules.

Original author description

Use when writing or fixing ExUnit tests — DataCase/ConnCase, generated fixtures and scopes, LiveView test helpers, uploads, Mox and Req.Test stubs, async and sandbox rules.

How it works

  1. RULES — Follow these with no exceptions
  2. TDD Workflow
  3. Case Templates
  4. Fixtures
  5. Context Test Skeleton
  6. LiveView Test Skeleton
  7. Changeset Test Skeleton
  8. Mocks: Mox at Behaviour Boundaries
  9. HTTP: Req.Test Stubs
  10. Processes, Logs, Files
Original SKILL.md headings · 381 lines, 1,895 words
SKILL.md preview
---
name: testing-essentials
description: "Use when writing or fixing ExUnit tests — DataCase/ConnCase, generated fixtures and scopes, LiveView test helpers, uploads, Mox and Req.Test stubs, async and sandbox rules."
---

# Testing Essentials

> Verified against Elixir 1.20, Phoenix 1.8, LiveView 1.2, Ecto 3.14, Req 0.7 — October 2026

For longer worked examples (a full context + LiveView suite, uploads, Mox wiring, sandbox allowances, StreamData), read the [testing reference](reference.md) when the patterns below aren't enough.

## RULES — Follow these with no exceptions

1. **Follow the project's existing test setup patterns** (e.g. shared setup helpers like `setup :store_test_session`) — don't inline DataCase/ConnCase boilerplate that the project already abstracts away
2. **Test both happy path AND error/invalid cases** for every function
3. **Prefer `async: true` — it is safe under the Ecto SQL Sandbox**, for DataCase and ConnCase/LiveView tests alike. Opt out only for real shared state: `Application.put_env`, named or app-supervised processes, Mox/Req.Test global mode. (Generators are inconsistent: phx.gen.auth's web tests are async, but its `accounts_test.exs` and the phx.gen.live / phx.gen.context tests aren't — add it.)
4. **Use the generated fixtures and scopes** — `user_fixture/1`, `user_scope_fixture/0`, `post_fixture(scope, attrs)`, and `setup :register_and_log_in_user` (puts `conn`, `user` and `scope` in the context). New fixtures go in `test/support/fixtures/`, never inline across tests
5. **Test authorization both ways** — guests are redirected to `~p"/users/log-in"`, and a record created under one scope can't be read or changed through another
6. **Assert LiveView structure with `has_element?/3`**, not `html =~` on markup. When an event navigates, pipe into `follow_redirect/2` and assert on the page you land on — the old view is gone
7. **Mock only at boundaries** — Mox against a behaviour with `setup :verify_on_exit!`; HTTP through `Req.Test` stubs. Never mock your own contexts or Repo
8. **Never `Process.sleep/1`** — use `assert_receive`, `render_async/2`, `start_supervised!/1`
9. **Test the public context interface**, not private helpers or internal state
10. **Use `describe` blocks** to group tests by function or behavior

---

## TDD Workflow

Write the failing test first, run it, confirm it fails for the right reason, then implement the minimum to pass.

```bash
mix test test/my_app/blog_test.exs:42   # one test by line
mix test --failed                       # re-run only last run's failures
mix test --stale                        # only tests affected by changed modules
mix test --warnings-as-errors           # fail on compile warnings in test files (CI)
```

---

## Case Templates

`DataCase` (context and schema tests) has no `conn`. `ConnCase` (controllers, LiveViews) builds one and checks out the sandbox. Both call `setup_sandbox/1`, which starts a sandbox owner per test — that's why `async: true` is safe.

```elixir
defmodule MyApp.BlogTest do
  use MyApp.DataCase, async: true

  alias MyApp.Blog
  import MyApp.AccountsFixtures, only: [user_scope_fixture: 0]
  import MyApp.BlogFixtures
end

defmodule MyAppWeb.PostLiveTest do
  use MyAppWeb.ConnCase, async: true

  import Phoenix.LiveViewTest
  import MyApp.BlogFixtures
end
```

---

## Fixtures

Follow the shape `phx.gen.context` emits with scopes: the scope comes first, attrs merge over defaults, the record goes through the real context function.

```elixir
defmodule MyApp.BlogFixtures do
  def post_fixture(scope, attrs \\ %{}) do
    attrs = Enum.into(attrs, %{title: "some title", body: "some body"})
    {:ok, post} = MyApp.Blog.create_post(scope, attrs)
    post
  end
end
```

phx.gen.auth (1.8) registration is email-only. `user_fixture/1` already confirms the user via magic link; use `unconfirmed_user_fixture/1` for the unconfirmed case and `set_password/1` when a test needs a password. When you add a field to users, add it to `valid_user_attributes/1` — don't write a new user fixture.

Fixtures for a custom scope entry (`org_scope_fixture/0`, its `test_setup_helper`) are in the `phoenix-scopes-and-generators` skill.

---

## Context Test Skeleton

```elixir
describe "posts" do
  test "list_posts/1 returns only the scope's posts" do
    scope = user_scope_fixture()
    other_scope = user_scope_fixture()
    post = post_fixture(scope)
    _other = post_fixture(other_scope)

    assert Blog.list_posts(scope) == [post]
  end

  test "get_post!/2 raises for another user's post" do
    post = post_fixture(user_scope_fixture())
    assert_raise Ecto.NoResultsError, fn -> Blog.get_post!(user_scope_fixture(), post.id) end
  end

  test "create_post/2 with valid attrs sets the owner from the scope" do
    scope = user_scope_fixture()
    assert {:ok, %Post{} = post} = Blog.create_post(scope, %{title: "Hello", body: "Hi"})
    assert post.user_id == scope.user.id
  end

  test "create_post/2 with invalid attrs returns an error changeset" do
    assert {:error, %Ecto.Changeset{} = changeset} = Blog.create_post(user_scope_fixture(), %{})
    assert %{title: ["can't be blank"]} = errors_on(changeset)
  end
end
```

---

## LiveView Test Skeleton

Mirrors `phx.gen.live`'s `live_test.exs`. `render_change/1` returns HTML, so the apostrophe is escaped (`can't`). A submit that navigates must be followed; the flash is on the new page.

```elixir
defmodule MyAppWeb.PostLiveTest do
  use MyAppWeb.ConnCase, async: true

  import Phoenix.LiveViewTest
  import MyApp.BlogFixtures

  setup :register_and_log_in_user

  defp create_post(%{scope: scope}), do: %{post: post_fixture(scope)}

  test "redirects guests to log in" do
    assert {:error, {:redirect, %{to: path}}} = live(build_conn(), ~p"/posts")
    assert path == ~p"/users/log-in"
  end

  describe "Index" do
    setup [:create_post]

    test "lists the user's posts", %{conn: conn, post: post} do
      {:ok, lv, _html} = live(conn, ~p"/posts")
      assert has_element?(lv, "#posts-#{post.id}", post.title)
    end

    test "deletes a post", %{conn: conn, post: post} do
      {:ok, lv, _html} = live(conn, ~p"/posts")
      lv |> element("#posts-#{post.id} a", "Delete") |> render_click()
      refute has_element?(lv, "#posts-#{post.id}")
    end
  end

  describe "Form" do
    test "validates, then saves and redirects", %{conn: conn} do
      {:ok, lv, _html} = live(conn, ~p"/posts/new")

      assert lv
             |> form("#post-form", post: %{title: nil})
             |> render_change() =~ "can't be blank"

      assert {:ok, index_lv, _html} =
               lv
               |> form("#post-form", post: %{title: "New Post", body: "Body"})
               |> render_submit()
               |> follow_redirect(conn, ~p"/posts")

      html = render(index_lv)
      assert html =~ "Post created successfully"
      assert html =~ "New Post"
    end
  end
end
```

`<.input>` errors render as `<p class="... text-error">` in 1.8's `core_components.ex`, so a structural check is `has_element?(lv, "#post-form p.text-error", "can't be blank")` — `has_element?/3` matches decoded text, so no `&#39;` there.

### LiveViewTest helpers worth knowing

| Helper | Use |
|---|---|
| `render_async(lv)` | Await `assign_async`/`start_async`/`stream_async`, then render. Default timeout is 100 ms — pass a larger one for slow work |
| `assert_patch(lv, path)` | After a `push_patch` (same LiveView). Returns the path when called without one |
| `assert_redirect(lv, path)` | After `push_navigate` or `redirect` from an event; returns the flash map |
| `follow_redirect(result, conn)` | Mount the destination from a `{:error, {:redirect, _}}` result of `live/2` or a `render_*` call |
| `render_hook(lv, "event", params)` | Fire an event that a JS hook would push (no DOM element needed) |
| `live_isolated(conn, MyLive, session: %{})` | Mount a LiveView without a route — good for components and uploads |
| `open_browser(lv)` | Debug only: dumps current HTML to a browser. Never commit it |
| `form(lv, sel, data)` | Validates `data` against the form's markup: unknown fields, disabled inputs and select values not in the options raise `ArgumentError` |

`render_submit/1` sends the form's values *as currently rendered* plus what you gave `form/3` — not what an earlier `render_change` sent. Values survive only if the server re-rendered them into the inputs (`<.input field={@form[:x]}>` does; a `<select>` rendered without `selected` doesn't). Pass the full params to `form/3` on the submit too.

LiveView 1.1+ parses test HTML with **LazyHTML**, not Floki — `phx.new` adds `{:lazy_html, ">= 0.1.0", only: :test}`. Keep Floki as a dependency only if your own tests call `Floki` directly; prefer `has_element?/3` over hand-parsing.

---

## Changeset Test Skeleton

```elixir
describe "changeset/3" do
  test "requires title" do
    changeset = Post.changeset(%Post{}, %{}, user_scope_fixture())
    assert %{title: ["can't be blank"]} = errors_on(changeset)
  end
end
```

---

## Mocks: Mox at Behaviour Boundaries

Mox needs three pieces: a behaviour the real module implements, a config switch, and the mock defined in `test/test_helper.exs`. Without `setup :verify_on_exit!`, a `expect` that is never called passes silently.

```elixir
# lib/my_app/storage.ex — callers use MyApp.Storage.put/2, never the impl directly
defmodule MyApp.Storage do
  @callback put(key :: String.t(), data :: binary()) :: {:ok, String.t()} | {:error, term()}

  def put(key, data), do: impl().put(key, data)

  defp impl, do: Application.get_env(:my_app, :storage, MyApp.Storage.S3)
end

# config/test.exs:      config :my_app, :storage, MyApp.StorageMock
# test/test_helper.exs: Mox.defmock(MyApp.StorageMock, for: MyApp.Storage)

defmodule MyApp.AvatarsTest do
  use MyApp.DataCase, async: true

  import Mox

  setup :verify_on_exit!

  test "stores the avatar under the user's key" do
    scope = MyApp.AccountsFixtures.user_scope_fixture()

    expect(MyApp.StorageMock, :put, fn "avatars/" <> _, _data -> {:ok, "https://cdn.example/a.png"} end)

    assert {:ok, user} = MyApp.Avatars.update(scope, "png-bytes")
    assert user.avatar_url == "https://cdn.example/a.png"
  end
end
```

Mox expectations are per-process. Calls from `Task`s and LiveViews started by the test are allowed automatically (`$callers`); for any other process use `Mox.allow(MyApp.StorageMock, self(), pid)`. Full wiring in the [testing reference](reference.md).

---

## HTTP: Req.Test Stubs

Req is Phoenix 1.8's default HTTP client. Route requests through a named `Req.Test` plug in test config; stubs are per-test and async-safe.

```elixir
# lib/my_app/weather.ex (trimmed; the full client is in the http-clients-req skill)
defmodule MyApp.Weather do
  def current(city) do
    req_options = :my_app |> Application.get_env(__MODULE__, []) |> Keyword.get(:req_options, [])

    [base_url: "https://api.weather.example", url: "/v1/current", params: [city: city]]
    |> Keyword.merge(req_options)
    |> Req.request()
    |> case do
      {:ok, %Req.Response{status: 200, body: %{"celsius" => celsius}}} -> {:ok, celsius}
      {:ok, %Req.Response{status: status}} -> {:error, {:unexpected_response, status}}
      {:error, exception} -> {:error, exception}
    end
  end
end

# config/test.exs — retry: false or transport-error tests sleep through Req's backoff
# config :my_app, MyApp.Weather, req_options: [plug: {Req.Test, MyApp.Weather}, retry: false]

defmodule MyApp.WeatherTest do
  use ExUnit.Case, async: true

  test "parses the temperature" do
    Req.Test.stub(MyApp.Weather, fn conn -> Req.Test.json(conn, %{"celsius" => 21.5}) end)
    assert {:ok, 21.5} = MyApp.Weather.current("Lisbon")
  end

  test "surfaces transport errors" do
    Req.Test.stub(MyApp.Weather, &Req.Test.transport_error(&1, :timeout))
    assert {:error, %Req.TransportError{reason: :timeout}} = MyApp.Weather.current("Lisbon")
  end
end
```

Use `Req.Test.expect/3` + `setup {Req.Test, :verify_on_exit!}` when the number of calls matters. Client design, retry policy, allowances for app-started processes and Finch pools are in the `http-clients-req` skill.

---

## Processes, Logs, Files

```elixir
test "counter starts at zero" do
  # Stopped after the test. Unnamed, so async tests (and an app-started
  # MyApp.Counter) don't collide; pass a unique name if the API needs one.
  pid = start_supervised!({MyApp.Counter, name: nil})
  assert MyApp.Counter.value(pid) == 0
end

@tag :capture_log                                       # hide expected error logs
test "logs and returns an error on bad input" do
  assert {:error, :invalid} = MyApp.Importer.run("garbage")
end

test "warns about the retry" do
  log = ExUnit.CaptureLog.capture_log(fn -> MyApp.Importer.run("retry-me") end)
  assert log =~ "retrying"
end

@tag :tmp_dir                                           # unique dir per test, in context
test "writes the export", %{tmp_dir: dir} do
  path = Path.join(dir, "out.csv")
  :ok = MyApp.Export.write(path)
  assert File.exists?(path)
end
```

**Sandbox allowances.** The SQL sandbox connection belongs to the test process. `Task`s and LiveViews started from the test inherit it via `$callers`; a GenServer (even one from `start_supervised!`) or anything already running in the application tree does not, and fails with `DBConnection.OwnershipError` in async tests. Allow it explicitly:

```elixir
pid = start_supervised!(MyApp.Indexer)
Ecto.Adapters.SQL.Sandbox.allow(MyApp.Repo, self(), pid)
```

---

## Email and Jobs

`phx.new` configures `Swoosh.Adapters.Test` in `config/test.exs`. It sends `{:email, email}` to the delivering process and its `$callers`, so mail sent from a LiveView or `Task` under test reaches the test process.

```elixir
import Swoosh.TestAssertions

test "sends the invite" do
  {:ok, _} = MyApp.Teams.invite(user_scope_fixture(), "new@example.com")
  assert_email_sent(to: "new@example.com", subject: "You're invited")
end
```

For Oban jobs (`Oban.Testing`, `assert_enqueued`, `perform_job/2`), see the `oban-essentials` skill.

---

## Parameterized Tests (Elixir 1.18+)

Run a whole module once per parameter map; each map is merged into the test context. With `async: true` the parameter sets run concurrently.

```elixir
defmodule MyApp.CacheTest do
  use ExUnit.Case,
    async: true,
    parameterize: [%{adapter: MyApp.Cache.ETS}, %{adapter: MyApp.Cache.Mnesia}]

  test "round-trips a value", %{adapter: adapter} do
    :ok = adapter.put(:k, 1)
    assert adapter.get(:k) == 1
  end
end
```

For property-based tests (`use ExUnitProperties`, `check all`), see the [testing reference](reference.md).

---

## Timestamp Testing

Never hardcode dates — use relative timestamps so tests don't rot.

<!-- epg:bad -->
```elixir
# Bad — breaks after 2026
assert post.published_at == ~U[2026-01-15 12:00:00Z]
```

```elixir
# Good — within 5 seconds of now (abs: inserted_at is in the past, so the diff is negative)
assert abs(DateTime.diff(post.inserted_at, DateTime.utc_now(), :second)) < 5

# Good — relative dates for filtering/sorting
past = DateTime.add(DateTime.utc_now(:second), -7, :day)
future = DateTime.add(DateTime.utc_now(:second), 7, :day)
old_post = post_fixture(scope, published_at: past)
_future_post = post_fixture(scope, published_at: future)
assert Blog.list_published_posts(scope) == [old_post]
```
Files in this package (2)
  • SKILL.md 15 KB
  • reference.md 19 KB

Versions

The database has no other skills named testing-essentials.

Database snapshot: 13.11.2026 · package version bea904501c0c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100testing
    Write or repair Elixir tests with ExUnit, sandbox isolation, async reliability, Mox, ExMachina, and LiveViewTest. Use for test files, test setup, or failing/flaky tests. NOT for investigating an application bug outside the test suite.
  • 100testing
    Write or repair Elixir tests with ExUnit, sandbox isolation, async; Use for test files, test setup, or failing/flaky…
  • 90exunit-code-review
    Reviews ExUnit test code for proper patterns, boundary mocking with Mox, and test adapter usage. Use when reviewing _test.exs files or test helper configurations.
  • 90estack-testing
    Test Elixir/Phoenix behavior with ExUnit, Ecto sandbox, fakes, Mox, and LiveViewTest. Use when adding tests, isolating vendor calls, testing concurrent processes, or choosing browser coverage.
  • 100testing
    Guide for Elixir testing with ExUnit. Use when writing unit tests, implementing property-based tests, setting up mocks, or organizing test suites.
  • 100http-clients-req
    Use when calling external HTTP APIs with Req — client modules, Req.new options, retries and Retry-After, timeouts, Finch pools, idempotency keys, Req.Test stubs, SSRF-safe redirects. Not for Oban job structure (use oban-essentials) or serving JSON APIs (use phoenix-json-api).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.