InkSnap

InkSnap is a simple and lightweight snapshot testing library for Elixir

Installation

This package can be installed by adding :ink_snap to your list of dependencies in mix.exs:

def deps do
  [
    {:ink_snap, git: "https://github.com/coherentpath/ink_snap", tag: "v*.*.*", only: [:dev, :test]}
  ]
end

Usage

InkSnap is easy to use and is designed to integrate seamlessly with Elixir's ExUnit module.

Defining Snapshot Tests

Snapshot tests can be defined with the test_snapshot macro. This macro is syntactically similar to the normal test macro and interacts with other ExUnit entities in the same way.

defmodule SampleTest do
  use ExUnit.Case

  import InkSnap

  setup_all do
    %{foo: 1, bar: 2}
  end

  describe "Map.put/3" do
    @tag :sample_tag
    test_snapshot "will add a new pair to a map", ctx do
      ctx
      |> Map.put(:baz, 3)
      |> Map.take([:foo, :bar, :baz])
    end
  end
end

Updating Snapshot Files

Once a snapshot test is defined, a snapshot file can be generated by running the test with the SNAPSHOT_UPDATE flag set to true:

SNAPSHOT_UPDATE=true mix test test/sample_test.exs:12

InkSnap creates a snapshot directory for each test path and a snapshot file for each test. The snapshot directory structure mirrors the test path directory structure. For the example snapshot test above, the command would generate a file at the following location:

test/_snapshots/sample_test/test_map_put_3_will_add_a_new_pair_to_a_map.snap

Projects using InkSnap can also leverage the configured :snapshot_test_tag to create a custom alias for generating snapshots:

defmodule MyApp.MixProject do
  use Mix.Project

  def project do
    [
      aliases: ["snapshots.generate": &generate_snapshots/1],
      preferred_cli_env: ["snapshots.generate": :test],
      ...
    ]
  end

  defp generate_snapshots(args) do
    System.put_env("SNAPSHOT_UPDATE", "true")
    args = ["--only", "snapshot"] ++ args
    Mix.Tasks.Test.run(args)
  end

  ...
end

Running Snapshot Tests

Once a snapshot file has been created, a snapshot test can be run in the same way as a normal test:

mix test test/sample_test.exs:12

Configuration

InkSnap has a few few configuration options that can be set in the application config:

# In config/test.exs
config :ink_snap,
  snapshot_directory: "my_snapshot_dir",
  snapshot_test_tag: :my_test_tag

More specifically, the configuration options are:

• :snapshot_directory - A t:binary/0 denoting the name of the snapshot directory. Defaults to _snapshots.

• :snapshot_test_tag - An t:atom/0 denoting the tag that InkSnap uses to differentiate snapshot tests. Defaults to :snapshot.

Test Paths

InkSnap can also be used for projects with non-traditional test paths. For more information on how to configure multiple test paths, see the mix test docs.

In general, InkSnap creates a separate snapshot directory for each test path. The only exception is if one test path contains another. In that case, a snapshot directory is only created in the parent path. For example, consider a project with the following configuration:

# In mix.exs
def project do
  [
    test_paths: ["test", "other_test", "other_test/dir"]
  ]
end

InkSnap would only create two snapshot directories for the above project:

test/_snapshots
other_test/_snapshots

InkSnap requires that all snapshot tests exist within one of the project test paths. In conjunction with the above simplification, this constraint guarantees a consistent snapshot file location for every test.