Elixir Test Runner

This skill helps run ExUnit tests efficiently with proper filtering, debugging, and error analysis.

When to Use

•Running full test suite
•Testing specific files or tests
•Debugging test failures
•Running tests with coverage
•Testing in different environments

Basic Test Execution

Run All Tests

bash

mix test

Run Specific Test File

bash

mix test test/my_app/accounts_test.exs

Run Specific Test by Line Number

bash

mix test test/my_app/accounts_test.exs:42

Run Tests Matching Pattern

bash

# Run all tests with "user" in the name
mix test --only user

Test Filtering

By Tag

elixir

# In test file
@tag :integration
test "complex integration test" do
  # ...
end

bash

# Run only integration tests
mix test --only integration

# Exclude slow tests
mix test --exclude slow

# Run everything except integration
mix test --exclude integration

By Module Pattern

bash

# Run all controller tests
mix test test/**/controllers/*_test.exs

# Run all LiveView tests
mix test test/**/*_live_test.exs

Umbrella App Filtering

bash

# Run tests for specific app
mix test apps/my_app/test

# Run all umbrella tests
mix test --only apps

Debugging Options

With Trace (Detailed Output)

bash

mix test --trace

Shows each test as it runs - useful for hanging tests.

With Verbose Failures

bash

mix test --max-failures 1

Stops after first failure for faster debugging.

With Test Seed

bash

# Tests run in random order by default
# To reproduce specific order:
mix test --seed 123456

# See seed in output:
# "Randomized with seed 123456"

With IEx for Debugging

bash

# Add IEx.pry() in test code
mix test --trace

Test Output Control

Show Only Failures

bash

mix test --failed

Reruns only previously failed tests.

Stale Tests

bash

mix test --stale

Only runs tests for changed files.

With Coverage

bash

mix test --cover

Generates coverage report in cover/ directory.

Quiet Mode

bash

mix test --quiet

Less verbose output.

Test Environments

Standard Test Run

bash

mix test

Uses MIX_ENV=test automatically.

With Database Reset

bash

mix ecto.reset && mix test

Fresh database for each run.

CI Mode

bash

# Ensure warnings fail, run with coverage
mix test --warnings-as-errors --cover

Common Test Patterns

Test Suite Organization

Unit Tests (fast, isolated):

bash

mix test test/my_app/accounts/user_test.exs

Integration Tests (slower, with database):

bash

mix test --only integration

Controller Tests:

bash

mix test test/my_app_web/controllers/

LiveView Tests:

bash

mix test test/my_app_web/live/

Parallel Testing

elixir

# In test_helper.exs - already default
ExUnit.start()

# In DataCase
use MyApp.DataCase, async: true  # Parallel execution

bash

# Run with more cores
mix test --max-cases 8

Analyzing Test Failures

Read Failure Output Carefully

Example failure:

code

1) test creates user with valid attrs (MyApp.AccountsTest)
   test/my_app/accounts_test.exs:42
   ** (RuntimeError) Database not started

What to check:

•Test name: "creates user with valid attrs"
•Module: MyApp.AccountsTest
•File and line: test/my_app/accounts_test.exs:42
•Error: Database not started

Common Failure Patterns

Database Not Started:

bash

# Start database
mix ecto.create
MIX_ENV=test mix ecto.migrate

Async Test Conflicts:

elixir

# Change to synchronous if tests conflict
use MyApp.DataCase, async: false

Missing Setup:

elixir

# Check for missing setup block
setup do
  :ok = Ecto.Adapters.SQL.Sandbox.checkout(Repo)
end

Factory/Fixture Issues:

bash

# Verify factory data is valid
mix test test/support/fixtures.exs --trace

Performance Optimization

Identify Slow Tests

bash

# Run with timing
mix test --trace | grep -E "^\s+test.*\([0-9]+\.[0-9]+s\)"

Profile Test Suite

bash

# With profiling
mix test --profile

Parallel Execution

elixir

# Enable async for fast unit tests
use MyApp.DataCase, async: true

# Disable for integration tests
use MyApp.DataCase, async: false

Test Coverage

Generate Coverage Report

bash

mix test --cover

View report: cover/excoveralls.html

Coverage Configuration

elixir

# In mix.exs
def project do
  [
    test_coverage: [tool: ExCoveralls],
    preferred_cli_env: [
      coveralls: :test,
      "coveralls.detail": :test,
      "coveralls.post": :test,
      "coveralls.html": :test
    ]
  ]
end

With ExCoveralls

bash

# HTML report
mix coveralls.html

# Detailed console report
mix coveralls.detail

# Check coverage threshold
mix coveralls --min-coverage 80

CI/CD Integration

GitHub Actions

yaml

- name: Run tests
  run: mix test --warnings-as-errors --cover

GitLab CI

yaml

test:
  script:
    - mix ecto.create
    - mix ecto.migrate
    - mix test --cover

Pre-commit Hook

bash

#!/bin/bash
# .git/hooks/pre-commit
mix test --failed || exit 1

Troubleshooting

Tests Hang

bash

# Use --trace to see which test hangs
mix test --trace

# Look for:
# - Database connection issues
# - Infinite loops
# - Missing async: false for conflicting tests

Tests Pass Locally, Fail in CI

Common causes:

•Missing MIX_ENV=test
•Database not created
•Dependencies not fetched
•Different Elixir/OTP versions
•Async test conflicts

Debug:

bash

# Reproduce CI environment locally
MIX_ENV=test mix do deps.get, ecto.create, ecto.migrate, test

Flaky Tests

bash

# Run same test multiple times
mix test test/my_app/accounts_test.exs:42 --trace
mix test test/my_app/accounts_test.exs:42 --trace
mix test test/my_app/accounts_test.exs:42 --trace

# Check for:
# - Time-dependent logic
# - Random data without seeds
# - Async conflicts
# - External dependencies

Memory Issues

bash

# Run with more memory
elixir --erl "+hms 4294967296" -S mix test

Best Practices

•Run tests frequently during development
•Use --stale for fast feedback loop
•Tag slow tests and exclude during dev
•Fix failures immediately - don't accumulate
•Use --trace when debugging
•Run full suite before committing
•Check coverage for critical code paths
•Keep tests fast - mock external services
•Use factories for consistent test data
•Run in CI to catch environment issues

Quick Reference

bash

# Development workflow
mix test --stale                    # Fast feedback
mix test test/my_app/file_test.exs # Specific file
mix test --failed                   # Rerun failures

# Debugging
mix test --trace                    # See each test
mix test --max-failures 1          # Stop at first failure
mix test --seed 123456             # Reproduce order

# Coverage
mix test --cover                    # Basic coverage
mix coveralls.html                  # Detailed HTML

# Filtering
mix test --only integration        # Tagged tests
mix test --exclude slow            # Exclude tagged

# CI/CD
mix test --warnings-as-errors --cover