ExUnit Test Framework

ExUnit Test Framework

Purpose

Provide ExUnit test execution and generation for Elixir projects, supporting:

• Test file generation from templates (_test.exs files)
• Test execution with Mix test integration
• Setup and setup_all callbacks
• Describe blocks for test organization
• Async testing support

Usage

Generate Test File

Create a test file from a bug report or feature description:

elixir generate-test.exs \
  --source lib/calculator.ex \
  --output test/calculator_test.exs \
  --module Calculator \
  --description "Division by zero error"

Execute Tests

Run ExUnit tests and return structured results:

elixir run-test.exs \
  --file test/calculator_test.exs \
  --format json

Command Line Options

generate-test.exs

• --source <path> - Source file to test (required)
• --output <path> - Output test file path (required)
• --module <name> - Module name to test (required)
• --description <text> - Bug description or test purpose
• --async - Enable async testing (default: false)

run-test.exs

• --file <path> - Test file to execute (required)
• --format <json|doc> - Output format (default: json)
• --trace - Run with detailed trace

Output Format

Test Generation

Returns JSON with generated test file information:

{
  "success": true,
  "testFile": "test/calculator_test.exs",
  "testCount": 1,
  "template": "unit-test",
  "async": false
}

Test Execution

Returns JSON with test results:

{
  "success": false,
  "passed": 2,
  "failed": 1,
  "total": 3,
  "duration": 0.234,
  "failures": [
    {
      "test": "test divide by zero raises ArithmeticError",
      "error": "Expected ArithmeticError to be raised",
      "file": "test/calculator_test.exs",
      "line": 15
    }
  ]
}

ExUnit Test Structure

Basic Test

defmodule CalculatorTest do
  use ExUnit.Case

  test "adds two numbers" do
    assert Calculator.add(1, 2) == 3
  end
end

With Describe Blocks

defmodule CalculatorTest do
  use ExUnit.Case

  describe "add/2" do
    test "adds positive numbers" do
      assert Calculator.add(1, 2) == 3
    end

    test "adds negative numbers" do
      assert Calculator.add(-1, -2) == -3
    end
  end

  describe "divide/2" do
    test "divides numbers" do
      assert Calculator.divide(6, 2) == 3
    end

    test "raises on division by zero" do
      assert_raise ArithmeticError, fn ->
        Calculator.divide(1, 0)
      end
    end
  end
end

With Setup Callbacks

defmodule UserTest do
  use ExUnit.Case

  setup do
    user = %User{name: "John", email: "john@example.com"}
    {:ok, user: user}
  end

  test "user has name", %{user: user} do
    assert user.name == "John"
  end

  test "user has email", %{user: user} do
    assert user.email == "john@example.com"
  end
end

Async Testing

defmodule FastTest do
  use ExUnit.Case, async: true

  test "runs in parallel with other async tests" do
    assert 1 + 1 == 2
  end
end

Common Assertions

• assert expr - Ensures expression is truthy
• refute expr - Ensures expression is falsy
• assert_raise Exception, fn -> ... end - Expects exception
• assert_received message - Asserts message was received
• assert x == y - Equality assertion (preferred over pattern matching)

Integration with deep-debugger

The deep-debugger agent uses this skill for Elixir projects:

1. Test Recreation: Generate failing test from bug report
2. Test Validation: Execute test to verify it fails consistently
3. Fix Verification: Re-run test after fix to ensure it passes

Example workflow:

1. deep-debugger receives bug report for Elixir project
2. Invokes test-detector to identify ExUnit
3. Invokes exunit-test/generate-test.exs to create failing test
4. Invokes exunit-test/run-test.exs to validate test fails
5. Delegates fix to elixir-phoenix-expert agent
6. Invokes exunit-test/run-test.exs to verify fix

Dependencies

Requires Elixir and Mix to be installed:

elixir --version  # Should be 1.12 or higher
mix --version     # Elixir's build tool

ExUnit is built into Elixir, no additional installation needed.

File Naming Conventions

• Test files must end with _test.exs
• Mirror source file structure: lib/calculator.ex → test/calculator_test.exs
• Test helper: test/test_helper.exs (required)

Error Handling

Test Generation Errors

{
  "success": false,
  "error": "Source file not found",
  "file": "lib/missing.ex"
}

Test Execution Errors

{
  "success": false,
  "error": "Mix test failed",
  "output": "** (CompileError) ..."
}

See Also

• ExUnit Documentation
• Elixir School Testing Guide
• templates/ - Test file templates