ArchUnit-inspired architecture testing library for Elixir.
Write ExUnit tests that enforce architectural rules — dependency direction, layer boundaries, bounded-context isolation, and naming conventions — using a fluent, pipe-based DSL.
Quick start
defmodule MyApp.ArchitectureTest do
use ExUnit.Case
use ArchTest
test "service modules don't call repos directly" do
modules_matching("**.*Service")
|> should_not_depend_on(modules_matching("**.*Repo"))
end
test "no Manager modules exist" do
modules_matching("MyApp.**.*Manager") |> should_not_exist()
end
endOptions for use ArchTest
:app— OTP app atom to limit introspection (default::all):freeze—trueto auto-freeze all rules in the module (default:false)
Module reference
ArchTest.ModuleSet— module selection and filtering DSLArchTest.Assertions— core assertion functionsArchTest.Layers— layered architecture enforcementArchTest.Modulith— bounded-context / modulith isolationArchTest.Freeze— violation baseline / freezingArchTest.Metrics— coupling/instability metricsArchTest.Conventions— pre-built Elixir convention rulesArchTest.Collector— BEAM dependency graph builderArchTest.Pattern— glob pattern matching
Summary
Functions
Returns a ModuleSet matching every module in the application.
Asserts every module under namespace_pattern belongs to a declared slice.
Asserts every module under namespace_pattern belongs to a declared slice.
Allows from_slice to call the public API of to_slice.
Defines an ordered list of architecture layers (top to bottom).
Defines an onion/hexagonal architecture (innermost layer first).
Defines bounded-context slices for a modulith architecture.
Enforces layer direction (each layer may only depend on layers below it).
Enforces bounded-context isolation (see ArchTest.Modulith).
Enforces onion architecture rules (dependencies point only inward).
Excludes modules matching pattern from a ModuleSet.
Returns modules present in both ModuleSets (intersection / AND).
Returns a ModuleSet for all direct children of namespace.
Returns a ModuleSet for modules matching the given glob pattern.
Returns a ModuleSet matching modules that satisfy a custom predicate.
Applies a custom check function (graph, module -> [Violation.t()]) to
each module in subject.
Asserts no circular dependencies among modules in subject.
Asserts all modules in subject export the given function.
Asserts all modules in subject have the given module attribute.
Asserts all modules in subject have the given attribute with the given value.
Asserts that the number of modules matching subject satisfies the given constraints.
Asserts that all modules in subject have names matching name_pattern.
Asserts all modules in subject have at least one public function whose name
matches the given glob pattern.
Asserts that all modules in subject implement the given behaviour.
Asserts that all modules in subject implement the given protocol.
Asserts that no module in callers calls any module in object.
Asserts that no module in subject directly depends on modules in object.
Asserts that slices have absolutely no cross-slice dependencies (strict isolation).
Asserts that no module in subject exists.
Asserts no module in subject exports the given function.
Asserts all modules in subject do NOT have the given module attribute.
Asserts all modules in subject do NOT have the given attribute with the given value.
Asserts no module in subject has public functions whose names match the pattern.
Asserts that no module in subject implements the given behaviour.
Asserts that no module in subject implements the given protocol.
Asserts no transitive dependency from subject to modules in object.
Asserts no module in subject uses the given module (via use ModuleName).
Asserts only modules in allowed_callers may call modules in object.
Asserts that modules in subject only depend on modules in allowed.
Asserts that all modules in subject reside under namespace_pattern.
Asserts all modules in subject use the given module (via use ModuleName).
Combines two ModuleSets (union / OR).
Functions
@spec all_modules() :: ArchTest.ModuleSet.t()
Returns a ModuleSet matching every module in the application.
Asserts every module under namespace_pattern belongs to a declared slice.
Asserts every module under namespace_pattern belongs to a declared slice.
@spec allow_dependency(ArchTest.Modulith.t(), atom(), atom()) :: ArchTest.Modulith.t()
Allows from_slice to call the public API of to_slice.
@spec define_layers(keyword()) :: ArchTest.Layers.t()
Defines an ordered list of architecture layers (top to bottom).
Example
define_layers(
web: "MyApp.Web.**",
context: "MyApp.**",
repo: "MyApp.Repo.**"
)
|> enforce_direction()@spec define_onion(keyword()) :: ArchTest.Layers.t()
Defines an onion/hexagonal architecture (innermost layer first).
Example
define_onion(
domain: "MyApp.Domain.**",
application: "MyApp.Application.**",
adapters: "MyApp.Adapters.**"
)
|> enforce_onion_rules()@spec define_slices(keyword()) :: ArchTest.Modulith.t()
Defines bounded-context slices for a modulith architecture.
Example
define_slices(
orders: "MyApp.Orders",
inventory: "MyApp.Inventory",
accounts: "MyApp.Accounts"
)
|> allow_dependency(:orders, :accounts)
|> enforce_isolation()@spec enforce_direction(ArchTest.Layers.t()) :: :ok
Enforces layer direction (each layer may only depend on layers below it).
@spec enforce_isolation(ArchTest.Modulith.t()) :: :ok
Enforces bounded-context isolation (see ArchTest.Modulith).
@spec enforce_onion_rules(ArchTest.Layers.t()) :: :ok
Enforces onion architecture rules (dependencies point only inward).
Excludes modules matching pattern from a ModuleSet.
Example
modules_matching("MyApp.**")
|> excluding("MyApp.Test.*")Returns modules present in both ModuleSets (intersection / AND).
@spec modules_in(String.t()) :: ArchTest.ModuleSet.t()
Returns a ModuleSet for all direct children of namespace.
Shorthand for modules_matching("Namespace.*").
Example
modules_in("MyApp.Orders")
# equivalent to modules_matching("MyApp.Orders.*")@spec modules_matching(String.t()) :: ArchTest.ModuleSet.t()
Returns a ModuleSet for modules matching the given glob pattern.
Pattern semantics
| Pattern | Matches |
|---|---|
"MyApp.Orders.*" | Direct children only |
"MyApp.Orders.**" | All descendants at any depth |
"MyApp.Orders" | Exact match only |
"**.*Service" | Last segment ends with Service |
"**.*Service*" | Last segment contains Service |
Example
modules_matching("**.*Controller")
|> should_not_depend_on(modules_matching("**.*Repo"))@spec modules_satisfying((module() -> boolean())) :: ArchTest.ModuleSet.t()
Returns a ModuleSet matching modules that satisfy a custom predicate.
Example
modules_satisfying(fn mod ->
function_exported?(mod, :__schema__, 1)
end)
|> should_reside_under("MyApp.**.Schemas")Applies a custom check function (graph, module -> [Violation.t()]) to
each module in subject.
Asserts no circular dependencies among modules in subject.
Asserts all modules in subject export the given function.
Asserts all modules in subject have the given module attribute.
Asserts all modules in subject have the given attribute with the given value.
Asserts that the number of modules matching subject satisfies the given constraints.
Asserts that all modules in subject have names matching name_pattern.
Asserts all modules in subject have at least one public function whose name
matches the given glob pattern.
Asserts that all modules in subject implement the given behaviour.
Asserts that all modules in subject implement the given protocol.
Asserts that no module in callers calls any module in object.
Asserts that no module in subject directly depends on modules in object.
@spec should_not_depend_on_each_other(ArchTest.Modulith.t()) :: :ok
Asserts that slices have absolutely no cross-slice dependencies (strict isolation).
Asserts that no module in subject exists.
Asserts no module in subject exports the given function.
Asserts all modules in subject do NOT have the given module attribute.
Asserts all modules in subject do NOT have the given attribute with the given value.
Asserts no module in subject has public functions whose names match the pattern.
Asserts that no module in subject implements the given behaviour.
Asserts that no module in subject implements the given protocol.
Asserts no transitive dependency from subject to modules in object.
Asserts no module in subject uses the given module (via use ModuleName).
Asserts only modules in allowed_callers may call modules in object.
Asserts that modules in subject only depend on modules in allowed.
Asserts that all modules in subject reside under namespace_pattern.
Asserts all modules in subject use the given module (via use ModuleName).
Combines two ModuleSets (union / OR).
Example
modules_matching("**.*Service")
|> union(modules_matching("**.*View"))