View Source README

CI Hex.pm Hex Docs Total Downloads Licence

TestIex

TestIex is an interactive ExUnit test runner, that provides following features:

  • Easy to learn:

    • the public API consists of 3 functions:
      • TestIex.run(matcher // "")
      • TestIex.run(matcher, line)
      • TestIex.watch(matcher // "")
      • TestIex.watch(matcher, line)
      • TestIex.unwatch()
  • Rapid feedback:

    • since there is no re-incurring cost of starting an OS process with Elixir + Mix + your code for every run
  • With sensible defaults:

    • you won't have to spend a lot of time to get it configured. Default configs provide great experience for the majority of Elixir projects
  • Usable

    • File event de-duplication during watch mode means you only run tests once, even if there are rapid multiple consecutive file events for a single file
  • Robust

    • it does code recompilation + loading of tests in a predictable manner
  • Flexible:

    • should you have some special needs, there are config options to tune.
    • they are all conveniently kept in a single module TestIex.Config.
    • heck, you could even swap the TestIex.Core module, if desired! It exposes only 3 public functions:
      • start()
      • test(files)
      • test(file, line)
  • Inspectable

    • you can turn on debug logs to see what happens
    • this helps you to narrow down issues with your configuration
  • Support for test file co-location:

  • Low - tech:

    • it does not require a particular editor extension or similar. Just simple Elixir + ExUnit in your terminal.
    • your workflow wont have to change in future, since the foundation for TestIex is very stable:
      • ExUnit + file system watching + Iex
  • Maintainable:

    • since it requires very little code, it's very easy to maintain and adjust on new Elixir releases
    • the core is in TestIex.Core.
    • It is less than 40 lines of Elixir code with lots of docs.
    • besides it does not have any hairy GenServer logic and also has no ambitions to grow more features and become more complex
    • by not supporting umbrella projects, we keep the code complexity much lower
    • every Elixir project is considered to be in a single root folder with following directories under it:
      • lib
      • test

Please give it a try and see if you like it!

usage

Usage

$ MIX_ENV=test iex -S mix

# Run all tests
iex> TestIex.run

# Run all matching files
iex> TestIex.run("word")

# Run test on line 45 for the first matching file
iex> TestIex.run("word", 45)

# Run test on line 45 for the first matching file
iex> TestIex.run("users_test.exs:45")

# Run test on line 45 for the first matching file
iex> TestIex.run("users:45")

# Watching on file changes and re-running tests.
# Currently only .ex / .exs files in `lib` or `test` folders trigger a re-run.
iex> TestIex.watch("users:45")

# Reset watching
iex> TestIex.unwatch()

configuration

Configuration

# in config/runtime.exs
import Config

if config_env() == :test do
  # for default values look into:
  # - https://github.com/maxohq/maxo_test_iex/blob/main/lib/test_iex/config.ex

  # NO need to watch for tests on CI
  if System.get_env("CI"), do: config :maxo_test_iex, watcher_enable: false

  # how long multiple consecutive events on the same file should be considered duplicates?
  config :maxo_test_iex, watcher_dedup_timeout: 500

  # which file changes should trigger a test re-run?
  config :maxo_test_iex, watcher_args: [dirs: ["lib/", "test/"], latency: 0]

  # which file extensions are relevant to trigger a test re-run?
  config :maxo_test_iex, watcher_extensions: [".ex", ".exs"]

  # should we log debug messages?
  config :maxo_test_iex, debug: false
end

installation

Installation

def deps do
  [
    {:maxo_test_iex, "~> 0.1", only: [:test]},
  ]
end

alternatives

Alternatives

support

Support

Sponsored by Quantor Consulting

license

License

The lib is available as open source under the terms of the MIT License.