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:

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

Search AI Tools

Install this agent skill to your Project

SKILL.md

Elixir Test Runner

When to Use

Basic Test Execution

Run All Tests

Run Specific Test File

Run Specific Test by Line Number

Run Tests Matching Pattern

Test Filtering

By Tag

By Module Pattern

Umbrella App Filtering

Debugging Options

With Trace (Detailed Output)

With Verbose Failures

With Test Seed

With IEx for Debugging

Test Output Control

Show Only Failures

Stale Tests

With Coverage

Quiet Mode

Test Environments

Standard Test Run

With Database Reset

CI Mode

Common Test Patterns

Test Suite Organization

Parallel Testing

Analyzing Test Failures

Read Failure Output Carefully

Common Failure Patterns

Performance Optimization

Identify Slow Tests

Profile Test Suite

Parallel Execution

Test Coverage

Generate Coverage Report

Coverage Configuration

With ExCoveralls

CI/CD Integration

GitHub Actions

GitLab CI

Pre-commit Hook

Troubleshooting

Tests Hang

Tests Pass Locally, Fail in CI

Flaky Tests

Memory Issues

Best Practices

Quick Reference