A Unit, Integration, and System Tests Framework for LFE
- Introduction
- Dependencies
- EUnit compatibility
- Features
- Quick start
- Test modules and names
- Creating unit tests
- Generators, named tests and test sets
- Fixtures
- Skipping tests
- Runner options and results
- The LFE test runner
- Dogfood
- Development checks
- License
ltest runs LFE tests through EUnit and separates unit, system, and integration
modules using marker behaviors. It provides LFE assertion macros, lazy EUnit
test objects, skip reporting, and a text reporter.
This source tree identifies the application as 0.14.0. The Hex badge reports
the package version currently available from Hex.
The testing DSL is inspired by Clojure's testing library. Its macros give EUnit assertions a Lispy form, while the custom listener makes passing, failing and skipped tests easy to distinguish in coloured output.
Use Rebar3 with LFE 2.2.2 and the rebar3_lfe plugin shown below. The
current development checks use Rebar3 3.28.0 on OTP 27, 28 and 29; the exact
versions are listed under Development checks.
For historical projects, ltest 0.11.0 introduced LFE 2.0 support. The
0.7.0 line switched to Rebar3; 0.6.3 is the documented legacy release
for projects still using Rebar2.
ltest test macros produce ordinary EUnit tests and test objects. Compiled
tests can be run from Erlang or LFE with EUnit's standard listener, or with
the ltest listener. For example, the quick-start module below can be run
with eunit:test('calculator-tests', [verbose]) from Erlang, or as part of:
rebar3 as test eunitThe ltest runner adds marker-based unit/integration/system selection and reports explicitly exported skipped tests. A plain EUnit run does not list those manually skipped functions.
deftestdefines ordinary EUnit tests with immediate assertion macros.deftestgendefines generators, including EUnit setup/teardown fixtures.deftestskipmarks work to be skipped and reported by the ltest listener.- Lists group test objects into sets, which may be nested.
- Named tuples give test objects readable descriptions.
- Marker behaviors separate unit, integration and system test modules.
- A custom listener reports results, skipped tests, elapsed time and failures with optional colour.
For an LFE project using ltest 0.14.0, add this root configuration:
{deps, [{lfe, "2.2.2"}]}.
{project_plugins, [{rebar3_lfe, "0.5.8"}]}.
{profiles, [
{test, [
{deps, [{ltest, "0.14.0"}]},
{erl_opts, [{src_dirs, ["src", "test"]}]}
]}
]}.The root project needs its own LFE dependency and provider plugin for the lfe
command; Rebar does not inherit a dependency's project_plugins entry. The test
profile adds test/ to the LFE source directories so ltest can discover the
compiled marker-behavior modules from the application's ebin directory.
Published 0.13.x packages are historical; this recipe describes 0.14.0.
The candidate's pre-publication consumer check uses the official
rebar3 hex build source archive as an ordinary Git dependency. That validates
the archive contents and consumer build; it is not a Hex install. The recipe
above uses the Hex dependency when version 0.14.0 is available. Run this
repository's source checks with make check-native.
In a test module, include the public macro header and mark the module's test group:
(defmodule calculator-tests
(behaviour ltest-unit)
(export all))
(include-lib "ltest/include/ltest-macros.lfe")
(deftest adds-two-numbers
(is-equal 5 (+ 2 3)))Run a selected group with the LFE Rebar3 provider:
rebar3 as test lfe ltest
rebar3 as test lfe ltest -tintegration
rebar3 as test lfe ltest -tsystem
rebar3 as test lfe ltest -tallThe test type names are unit, integration, system, and all. The all
group runs unit, system, and integration tests in that order. Its return value
is the first non-ok group result; later groups still run.
The complete macro reference, behavior contracts, and source examples are in
docs/overview.md. The native API reference includes the
exported helpers as well as the main runner functions.
Place test modules under test/, compiled as BEAM modules. Mark each module
with one of the behaviors ltest-unit, ltest-system, or
ltest-integration. These behaviors are marker interfaces with no callbacks;
ltest discovers modules from their behavior attributes, then runs the
selected BEAMs through EUnit.
deftest NAME defines a nullary NAME_test/0; deftestgen NAME defines a
nullary generator NAME_test_/0; and deftestskip NAME defines a nullary
NAME_skip/0. Export it explicitly or use export all for the custom reporter
to list it as skipped. The reporter
does not execute the function. Ordinary EUnit _test and _test_ naming
still applies to tests that do not use these macros. The skip list recognizes
exported nullary names ending exactly in _skip.
LFE names may contain dashes. Test definition macros convert dashes to underscores in generated Erlang function names. Fixture and generated-test names should follow EUnit's naming and arity rules.
A useful starting layout is one test module per source module, splitting larger suites further when that makes the tests easier to navigate:
src/myproj-base.lfe
src/myproj-util.lfe
test/myproj-base-tests.lfe
test/myproj-util-tests.lfe
The filename must match the declared module: myproj-base-tests.lfe
declares (defmodule myproj-base-tests ...). A -tests suffix is a naming
convention; ltest selects modules by their compiled behavior attributes.
Keep test modules in test/ with the test-profile configuration above.
Simply adding tests to an unmarked application module does not put that
module into one of ltest's groups.
Choose (behaviour ltest-unit), (behaviour ltest-integration) or
(behaviour ltest-system) in each test module according to its role.
See the project's own test directory for examples of each group.
Include ltest-macros.lfe to use the assertion and definition macros.
deftest supplies the empty argument list, EUnit suffix and export for you:
(deftest adds-two-numbers ...) defines adds_two_numbers_test/0. If you
write a test with defun instead, give it a nullary _test name and export
it for EUnit to discover.
Save this complete example as test/arithmetic-tests.lfe:
(defmodule arithmetic-tests
(behaviour ltest-unit)
(export (pending_division_skip 0)))
(include-lib "ltest/include/ltest-macros.lfe")
(deftest true-and-false
(is 'true)
(is-not 'false))
(deftest equality
(is-equal 5 (+ 2 3))
(is-not-equal 1 1.0))
(deftest pattern-matching
(is-match (tuple 'ok _) (tuple 'ok 42)))
(deftestskip pending-division
(error 'not-implemented-yet))is-equal uses exact term equality, so 1 and 1.0 are different. The
macro reference covers
all assertion families, including errors, exits, throws and pattern matches.
A deftest body executes assertions immediately. A deftestgen body returns
EUnit test objects to be executed later; use the delayed assertion forms
ending in * when constructing those objects. Lists form test sets, nested
lists form nested sets, and a {Description, Test} tuple names a test or set.
Save this as test/arithmetic-generator-tests.lfe:
(defmodule arithmetic-generator-tests
(behaviour ltest-unit))
(include-lib "ltest/include/ltest-macros.lfe")
(deftestgen additions
(list
(is-equal* 4 (+ 2 2))
(tuple "Nested additions"
(list
(is-equal* 6 (+ 3 3))
(is-equal* 8 (+ 4 4))))))Use delayed assertions inside the named tuple too. Returning the result of
an immediate assertion can produce a value instead of a valid EUnit test
object. are* is a documented exception to the delayed naming convention:
it substitutes rows and runs assertions immediately.
EUnit fixtures arrange setup, test instantiation and teardown. ltest's
defsetup, defteardown, deftestcase and deftestcases helpers let you
write those parts in LFE. Define each case before using it in deftestcases.
Save this as test/arithmetic-fixture-tests.lfe:
(defmodule arithmetic-fixture-tests
(behaviour ltest-unit))
(include-lib "ltest/include/ltest-macros.lfe")
(defun set-up ()
(tuple 1 2))
(defun tear-down (_pair)
'ok)
(deftestcase addition-case (pair)
(is-equal 3 (+ (element 1 pair) (element 2 pair))))
(deftestgen with-fixture
(tuple 'setup
(defsetup set-up)
(defteardown tear-down)
(deftestcases addition-case)))Setup supplies the value passed to the test case and teardown. For a fixture
that acquires a resource, release it in teardown. The repository includes
standard EUnit fixtures and
fixture-case helper examples, including
foreach cases.
The pending-division example above defines pending_division_skip/0.
It is explicitly exported so ltest can report it as skipped; its body is
never executed. deftestskip does not export the function for you.
EUnit's normal _test / _test_ selection ignores these _skip functions.
The ltest listener finds and counts them separately. See the
skipped-test example for a complete module.
ltest:default-opts/0 enables color, suite headers, and verbose output; it
selects ltest-listener and the unit test type. Public group /1
functions merge partial maps over these defaults and force their own group
type; /0 uses the complete defaults. Groups return EUnit's
canonical result. all/0,1 runs unit, system, and integration in that order
even after a failure, then returns the first non-ok result.
run/0 selects the default unit group. run/1 merges a partial map with the
defaults and dispatches its test-type; it maps EUnit error to
{error, tests_failed}, preserves other results, and returns an explanatory
{error, Message} for an unknown type. The EUnit option helpers require the
keys they read and do not merge defaults independently.
The built-in listener uses EUnit's eunit_listener callbacks. Its init/1
defaults omitted color to true and omitted test type to unit, preserving
explicit values. Set color to false to prevent the listener's standard
color wrappers from adding ANSI sequences.
The custom listener adds coloured progress, readable assertion failures and skip counts to EUnit's execution. These retained screenshots illustrate the reporter's appearance in earlier releases; test inventories and timings vary.
Failing and skipped tests:
Passing tests:
Use the runner options to disable colour or call the runner directly. The recommended command-line entrypoint is the Rebar3 LFE provider shown in Quick start.
ltest tests itself with ltest. From this source checkout, run all three groups through its custom listener:
make check-runner-ltestThe current unit summary is:
summary:
Tests: 113 Passed: 112 Skipped: 1 Failed: 0 Erred: 0
The system and integration groups each run two passing tests. For an uncoloured
report, run make check-runner-ltest-no-color. The complete native check below
also runs ordinary EUnit and both custom-listener colour modes. The
test sources provide more examples of assertions, generators, named
and nested sets, fixtures and skip reporting.
The repository's native check is:
make check-nativeThe checked workflow runs this command with Rebar3 3.28.0 on OTP
27.3.4.19, 28.5.0.8, and 29.1.2. These are tested versions, not an
asserted minimum or maximum support boundary. Its build badge points at the
maintained release/0.14.x branch; the Hex badge remains the live publication
version.
Generate the local reference with make docs, which uses the published ldoc
Rebar3 plugin. Open _build/default/ldoc/current/site/index.html.
BSD 3-Clause License. See LICENSE.
Copyright © 2013-2026, Duncan McGreggor <oubiwann@gmail.com>
Copyright © 2014, Døkkarr Hirðisson <dokkarr@lfe.io>,
Joshua Schairbaum <joshua.schairbaum@gmail.com>
Copyright © 2016, Eric Bailey <eric@ericb.me>,
jsc <jonas.skovsgaard.christensen@gmail.com>