Glacier · Gleam Incremental Interactive Unit Testing

Under construction

Package Version Hex Docs

Introduction

Glacier brings incremental interactive unit testing to Gleam. It is meant as a drop-in replacement for Gleeunit and it relies on it, internally.

Glacier differs from Gleeunit insofar, that it let’s you:

  1. Pass in an interactive flag gleam test -- --glacier; save a module and only related tests will rerun.
  2. Pass in a specific unit test modules to rerun gleam test -- test/my_module_test.gleam.
  3. If gleam test is passed without any ---arguments it behaves the same as Gleeunit.
  4. You can still pass in --target erlang or --target javascript, like so: gleam test --target erlang -- --glacier or like gleam test --target javascript -- test/my_module_test.gleam.

To enable this behavior, all you have to do is add Glacier as a dev dependency, aka gleam add glacier, open ./test/YOUR_PROJECT.gleam and replace gleeunit.main() with glacier.main().

How does it work?

  1. gleam test passes through glacier.run() and simply executes gleeunit.main() as if Gleeunit was used directly.
  2. gleam test -- test_module_a test_module_b passes through glacier.run() and executes gleeunit.test_modules(modules_list) where modules_list is ["foo", "bar"]. The given modules are checked if they exist as either .gleam or .erl test module files and then Gleeunit runs these test modules.
  3. gleam test -- --glacier enters glacier.run() and starts a file watcher: Upon changes in module files in ./test it just passes those through as gleam test -- changed_test_module(so re-saving test files executes the single test), and if a module file in ./src got changed it parses that changed module file for any imported modules and puts the module and all chained imported modules in a distinct list of modules that should be tested. Then all test module files are read and imports of those are gathered one by one and cross matched against that list. The result is a list of test modules that need to be run, which then gets done by executing a shell call similar to gleam test -- detected_test_module_a detected_test_module_b detected_test_module_c etc, aka jumps to 2..

TODO

Known Caveats

Installation & Usage

For Erlang this library depends on fs. Because of this on Linux you will need inotify-tools to be installed. On Mac and Windows it should work out of the box.

For NodeJS version 18 LTS is supported and development always and only happens on the latest stable LTS, such as Node.js say v18.12.1.

If available on Hex this package can be added to your Gleam project:

  1. Run gleam add glacier
  2. Open ./test/YOUR_PROJECT.gleam and replace gleeunit.main() with glacier.main()
  3. Run gleam test
    • save any test module (within ./test) file to re-run that single test
    • save any src module (within ./src) to run all associated tests. Associated tests are test modules where the module is imported or where any of the module’s imports and their import’s imports (import chain) are imported into.

… and its documentation can be found at https://hexdocs.pm/glacier.

Quick start

git clone https://github.com/inoas/glacier.git
cd glacier
gleam run   # Show instructions how to use the library stand alone
gleam test  # Run the tests on this library

Status

Alpha quality, thus while this is still…

Under construction

…it should be working now.

Search Document