Skip to content

Testing

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Testing

Laravex is built for testability. Tests are plain ExUnit modules; the framework provides a Laravex.TestCase base module that boots the application and exposes HTTP helpers mirroring Laravel's TestCase conventions.

Directory Structure

Tests live in the tests/ directory (configured as the test_paths in mix.exs):

tests/
├── test_helper.exs         # ExUnit.start()
├── test_case.ex            # Laravex.TestCase base module
├── Feature/
│   └── example_test.exs    # HTTP/integration tests
└── Unit/
    └── example_test.exs    # Pure unit tests

Test files use the .exs extension and the _test suffix. The test pattern is *_test.exs.

Running Tests

mix test                        # all tests
mix test tests/Unit/            # a specific directory
mix test tests/Feature/example_test.exs  # a single file
mix test tests/Feature/example_test.exs:5  # a specific line

For verbose output:

mix test --trace

Laravex.TestCase

Base module for integration / HTTP tests. Use it in a test module with use Laravex.TestCase:

defmodule Tests.Feature.HomeTest do
  use Laravex.TestCase, async: false

  test "homepage returns 200" do
    response = get("/")
    assert_status(response, 200)
    assert_see(response, "Laravex")
  end
end

Use async: false when tests share database state; async: true is safe for stateless or in-memory tests.

Setup

TestCase calls Laravex.Foundation.Server.boot!/0 in setup, which boots the full application stack (config, routes, middleware) before each test.

HTTP Helpers

# GET request — returns a %Laravex.Http.Response{}
response = get("/posts/1")
response = get("/posts", %{}, %{"Authorization" => "Bearer token"})

# POST / JSON requests
response = post("/posts", %{"title" => "Hello"})
response = json(:post, "/api/posts", %{"title" => "Hello"})
response = json(:get, "/api/user")

# Assertions
assert_status(response, 200)
assert_see(response, "expected text")    # substring check on response.body
assert_json(response, %{"id" => 1})     # checks parsed JSON body subset
assert_database_has("posts", %{"title" => "Hello"})  # row exists in DB
assert_database_missing("posts", %{"id" => 999})     # row absent from DB

Acting As a User

user = Database.Factories.UserFactory.create()

response = acting_as(user, fn ->
  get("/dashboard")
end)

acting_as/2 stores the user in the process dictionary so Guard.user/1 resolves it without touching the session.

Disabling Middleware

response = without_middleware(fn ->
  post("/admin/secret", %{"key" => "value"})
end)

Faking Events, Mail, and Notifications

# Fake the event dispatcher (listeners still run unless run_listeners: false)
Laravex.Events.Dispatcher.fake()

post("/posts", %{"title" => "Hello"})

Laravex.Events.Dispatcher.assert_dispatched(fn {event, _payload} ->
  event == :post_created
end)

# Fake notifications (suppress actual delivery)
Laravex.Notifications.Channel.fake()
Laravex.Notifications.Channel.assert_sent(fn {_notifiable, mod, _payload} ->
  mod == App.Notifications.WelcomeEmail
end)

Unit Tests

For pure unit tests that do not need the HTTP stack, use ExUnit.Case directly:

defmodule Tests.Unit.HashTest do
  use ExUnit.Case, async: true

  test "hashes and verifies a password" do
    hashed = Laravex.Hashing.Hash.make("secret")
    assert Laravex.Hashing.Hash.check("secret", hashed)
    refute Laravex.Hashing.Hash.check("wrong", hashed)
  end
end

Feature Tests

Feature tests exercise the full request lifecycle through Laravex.Http.Kernel:

defmodule Tests.Feature.PostTest do
  use Laravex.TestCase, async: false

  test "can view a published post" do
    user = Database.Factories.UserFactory.create()
    post = Database.Factories.PostFactory.create(%{
      "user_id"   => user.id,
      "published" => true
    })

    response = get("/posts/#{post.id}")
    assert_status(response, 200)
    assert_see(response, post.title)
  end

  test "health endpoint is up" do
    response = get("/up")
    assert_status(response, 200)
  end
end

Test Database

Tests use the same SQLite database as development by default. Reset it before a run with:

./artisan migrate:fresh
./artisan db:seed
mix test

For fully isolated test runs, set a separate database path in config/test.exs:

# config/test.exs
%{
  "database" => %{
    "connections" => %{
      "sqlite" => %{"database" => "database/test.sqlite"}
    }
  }
}

Factories in Tests

Use Eloquex-Factories to create model fixtures:

user = Database.Factories.UserFactory.create()
post = Database.Factories.PostFactory.create_state(:published, %{"user_id" => user.id})

See Also

Clone this wiki locally