Augments ExUnit.Assertions with a set of assertions that know how to update themselves.

To learn more about how Mneme's auto-assertions are updated, see the pattern generation guide.

use Mneme

When you use Mneme in a test module, assertions are imported and module attributes are made available for configuration.

Configuration

Mneme supports a variety of flexible configuration options that can be applied at multiple levels of granularity, from your entire test suite down to an individual test. While the default behavior will work well for the majority of cases, it's worth knowing which levers and knobs you have available to tweak Mneme to fit your individual workflow.

Options

• :action (:prompt | :accept | :reject) - The action to be taken when an auto-assertion updates. If CI=true is set in environment variables, the action will always be :reject. The default value is :prompt.

• :default_pattern (:infer | :first | :last) - The default pattern to be selected if prompted to update an assertion. The default value is :infer.

• :diff (:text | :semantic) - Controls the diff engine used to display changes when an auto- assertion updates. If :semantic, uses a custom diff engine to highlight only meaningful changes in the value. If :text, uses the Myers Difference algorithm to highlight all changes in text. The default value is :semantic.

• :diff_style (:side_by_side | :stacked) - Controls how diffs are rendered when the :diff option is set to :semantic. If :side_by_side, old and new code will be rendered side-by-side if the terminal has sufficient space. If :stacked, old and new code will be rendered one on top of the other. The default value is :side_by_side.

• :force_update (boolean/0) - Setting to true will force auto-assertions to update even when they would otherwise succeed. This can be especially helpful when adding new keys to maps or structs since a pattern like %{} would not normally prompt as the match still succeeds. The default value is false.

• :target (:mneme | :ex_unit) - The target output for auto-assertions. If :mneme, the expression will remain an auto-assertion. If :ex_unit, the expression will be rewritten as an ExUnit assertion. The default value is :mneme.

Configuring Mneme

There are four ways you can apply configuration options; Each is more specific than the last and will override any conflicting options that were set prior.

• When calling Mneme.start/1, which will apply to the entire test run;
• When calling use Mneme, which will apply to all tests in that module;
• In a @mneme_describe module attribute, which will apply to all tests that follow in the given ExUnit.Case.describe/2 block;
• In a @mneme module attribute, which will apply only to the next test that follows.

For instance, when an auto-assertion has multiple possible patterns available, Mneme will try to infer the best one to show you first. If you always want the last (and usually most complex) generated pattern, you could call Mneme.start/1 like this:

# test/test_helper.exs
ExUnit.start()
Mneme.start(default_pattern: :last)

As mentioned above, this can be overriden at the module-level, in a describe block, or for an individual test:

defmodule MyTest do
  use ExUnit.Case
  use Mneme, default_pattern: :infer

  test "the default pattern will exclude :baz when this runs" do
    map = %{foo: :one, baz: :three}
    auto_assert %{foo: 1, bar: 2} <- Map.put(map, bar: :two)
  end

  describe "..." do
    @mneme_describe action: :reject

    test "fails without prompting" do
      auto_assert :wrong <- MyModule.some_fun()
    end

    @mneme action: :prompt
    test "prompts to update" do
      auto_assert :wrong <- MyModule.another_fun()
    end
  end
end

Breaking up with Mneme? While the official stance of the library is that this is Not Recommended™, Mneme can even convert all of your existing auto-assertions to regular assertions:

Mneme.start(
  target: :ex_unit,
  force_update: true,
  action: :accept
)

Probably don't do this, but if you do, make sure all your tests are committed first in case you want to get back together.