mtrudel/machete

Literate test matchers for ExUnit

Machete

Machete provides ergonomic match operators to help make your ExUnit tests more literate

The easiest way to explain Machete is to show it in action:

defmodule ExampleTest do
  use ExUnit.Case
  use Machete

  test "example test" do
    response = %{
      id: 1,
      name: "Moe Fonebone",
      is_admin: false,
      created_at: DateTime.utc_now()
    }

    assert response ~> %{
      id: integer(positive: true),
      name: string(),
      is_admin: false,
      created_at: datetime(roughly: :now, time_zone: :utc)
    }
  end
end

At its heart, Machete provides the following two things:

• A new ~> operator (the 'squiggle arrow') that does flexible matching of its left operator with its right operator
• A set of parametric matchers such as string() or integer() which can match against general types. A comprehensive list of Machete's built-in matchers is available in the Machete documentation

These building blocks let you define test expectations that can match data against any combination of literals, variables, or parametrically defined matchers

When your matches fail, Machete provides useful error messages in ExUnit that point you directly at any failing matches using jq syntax

Installation

Machete is available in Hex, and can be installed by adding machete to your list of dependencies in mix.exs:

def deps do
  [
    {:machete, "~> 0.2.8"}
  ]
end

Documentation is published on HexDocs

License

MIT

machete's Issues

sorted_list matcher

Hi Mat!

Would you be interested in a sorted_list matcher?

I added one in ScenicFramework/scenic#335 for Scenic, but it would be nice to upstream it.

I think it would complement the existing InAnyOrderMatcher because the InAnyOrderMatcher has an exponential cost and the sorted_list matcher would not. In many cases it won't make a big difference, but I generally try to avoid exponential costs when they can be avoided and in this case I think it can.

Feature request: ISO 8601 naive date time matcher support

Machete has two DateTime matchers for structs:

• Machete.DateTimeMatcher
• Machete.NaiveDateTimeMatcher

But only one for strings:

• Machete.ISO8601DateTimeMatcher

Thus if you have a string like "2024-04-18 18:16:12.481210" then you can't use a machete matcher on it. If we're following the same pattern then we'd want to introduce a Machete.ISO8601NaiveDateTimeMatcher that can parse ""2024-04-18 18:16:12.481210".

Although instead of creating a whole new matcher it also might make sense to consider extending Machete.ISO8601DateTimeMatcher to match ISO8601 strings without a timezone so this could match, right now this is the behavior Machete has:

iex(8)> NaiveDateTime.to_iso8601(NaiveDateTime.utc_now()) ~>> Machete.ISO8601DateTimeMatcher.iso8601_datetime(roughly: :now)
[
  %Machete.Mismatch{
    path: [],
    message: "\"2024-04-20T19:37:31.381743\" is not a parseable ISO8601 datetime"
  }
]

Instead I'm proposing this:

iex(12)> NaiveDateTime.to_iso8601(NaiveDateTime.utc_now()) ~>> Machete.ISO8601DateTimeMatcher.iso8601_datetime(roughly: :now)
[]