View Source ParameterizedTest (ParameterizedTest v0.3.0)

A utility for defining eminently readable parameterized (or example-based) tests.

Parameterized tests look like this:

param_test "grants free shipping based on the marketing site's stated policy",
           \"\"\"
           | spending_by_category          | coupon      | gets_free_shipping? |
           | %{shoes: 19_99, pants: 29_99} |             | false               |
           | %{shoes: 59_99, pants: 49_99} |             | true                |
           | %{socks: 10_99}               |             | true                |
           | %{pants: 1_99}                | "FREE_SHIP" | true                |
           \"\"\",
           %{
             spending_by_category: spending_by_category,
             coupon: coupon,
             gets_free_shipping?: gets_free_shipping?
           } do
  shipping_cost = ShippingCalculator.calculate_shipping(spending_by_category, coupon)
  free_shipping? = shipping_cost == 0
  assert free_shipping? == gets_free_shipping?
end

Alternatively, if you don't like the Markdown table format, you can supply a hand-rolled list of parameters to the param_test macro, like this:

param_test "shipping policy matches the web site",
            [
              # Items in the parameters list can be either maps...
              %{spending_by_category: %{pants: 29_99}, coupon: "FREE_SHIP"},
              # ...or keyword lists
              [spending_by_category: %{shoes: 19_99, pants: 29_99}, coupon: nil]
            ],
            %{spending_by_category: spending_by_category, coupon: coupon} do
  ...
end

Just make sure that each item in the parameters list has the same keys.

The final option is to pass a path to a file that contains your test parameters (we currently support .md/.markdown, .csv, and .tsv files), like this:

param_test "pull test parameters from a file",
            "test/fixtures/params.md",
            %{
              spending_by_category: spending_by_category,
              coupon: coupon,
              gets_free_shipping?: gets_free_shipping?
            } do
  ...
end

Why parameterized testing?

Parameterized testing reduces toil associated with writing tests that cover a wide variety of different example cases. It also localizes the test logic into a single place, so that at a glance you can see how a number of different factors affect the behavior of the system under test.

As a bonus, a table of examples (with their expected results) often matches how the business communicates the requirements of a system, both internally and to customers—for instance, in a table describing shipping costs based on how much a customer spends, where they're located, whether they've bought a promotional product, etc. This means parameterized tests can often be initially created by pulling directly from a requirements document that your product folks provide, and the product folks can later read the tests (or at least the parameters table) if they want to verify the behavior of the system.

See the README for more information.

Summary

Functions

Link to this macro

param_test(test_name, examples, context_ast \\ %{}, blocks)

View Source (macro)

Defines tests that use your parameters or example data.

Use it like:

param_test "works as expected", your_parameters, %{value: from_context, expected_result: expected_result} do
  assert MyModule.process(from_context) == expected_result
end
Link to this function

parse_examples(table, context \\ [])

View Source
@spec parse_examples(String.t() | list(), context()) :: [map()]