exunit-test-framework

name	ExUnit Test Framework
description	Execute and generate ExUnit tests for Elixir projects with setup callbacks, describe blocks, and async testing support
version	1.0.0

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: "[e-mail]"}
    {: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 == "[e-mail]"
  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