Add param_feature to wrap Wallaby's feature macro (#21)

Author: s3cur3

.github/workflows/elixir-build-and-test.yml

@@ -35,7 +35,7 @@ jobs:
           build-flags: --all-warnings --warnings-as-errors
 
       - name: Run Tests
-        run: mix coveralls.json --warnings-as-errors
+        run: mix coveralls.json --warnings-as-errors --include feature --include integration
         if: always()
 
       # Optional, but Codecov has a bot that will comment on your PR with per-file

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.4.0
+
+- Adds a new `param_feature` macro, which wraps Wallaby's `feature` tests
+  the same way `param_test` wraps ExUnit's `test`.
+
+  (While you _can_ use the plain `param_test` macro in a test module that
+  contains `use Wallaby.Feature`, doing so will break some Wallaby features
+  including screenshot generation on failure.)
+- Moves the `parse_examples/2` function, an implementation detail for the
+  `param_test` macro, into a new private module `ParameterizedTest.Parser`.
+
 ## v0.3.1
 
 Bug fix to accept more unquoted strings, including those that have Elixir delimiters in them like quotes, parentheses, etc.

README.md

@@ -107,6 +107,12 @@ param_test "grants free shipping based on the marketing site's stated policy",
 end
 ```
 
+The package also provides a second macro, `param_feature`, which wraps
+Wallaby's `feature` tests the same way `param_test` wraps ExUnit's `test`.
+(While you _can_ use the plain `param_test` macro in a test module that
+contains `use Wallaby.Feature`, doing so will break some Wallaby features
+including screenshot generation on failure.)
+
 ## Why parameterized testing?
 
 Parameterized testing reduces toil associated with writing tests that cover

config/runtime.exs

@@ -0,0 +1,7 @@
+import Config
+
+if Mix.env() == :test do
+  config :wallaby,
+    driver: Wallaby.Chrome,
+    screenshot_on_failure: true
+end

lib/parameterized_test.ex

@@ -2,7 +2,7 @@ NimbleCSV.define(ParameterizedTest.TsvParser, separator: "\t", escape: "\"")
 NimbleCSV.define(ParameterizedTest.CsvParser, separator: ",", escape: "\"")
 
 defmodule ParameterizedTest do
-  @moduledoc ~S"""
+  @moduledoc """
   A utility for defining eminently readable parameterized (or example-based) tests.
 
   Parameterized tests look like this:
@@ -14,7 +14,7 @@ defmodule ParameterizedTest do
                  | %{shoes: 19_99, pants: 29_99} |             | false       | Spent too little |
                  | %{shoes: 59_99, pants: 49_99} |             | true        | Spent $100+      |
                  | %{socks: 10_99}               |             | true        | Socks ship free  |
-                 | %{pants: 1_99}                | "FREE_SHIP" | true        | Correct coupon   |
+                 | %{pants: 1_99}                | \"FREE_SHIP\" | true        | Correct coupon   |
                  \"\"\",
                  %{
                    spending_by_category: spending_by_category,
@@ -82,63 +82,37 @@ defmodule ParameterizedTest do
 
   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
+      param_test \"grants free shipping for spending $99+ or with coupon FREE_SHIP\",
+                 \"\"\"
+                 | total_cents | ships_free? | description                 |
+                 | ----------- | ----------- | --------------------------- |
+                 | 98_99       | false       | Spent too little            |
+                 | 99_00       | true        | Min for free shipping       |
+                 | 99_01       | true        | Spent more than the minimum |
+                 \"\"\",
+                 %{total_cents: total_cents, ships_free?: ships_free?} do
+        shipping_cost = ShippingCalculator.calculate(total_cents)
+
+        if ships_free? do
+          assert shipping_cost == 0
+        else
+          assert shipping_cost > 0
+        end
       end
+
   """
   defmacro param_test(test_name, examples, context_ast \\ %{}, blocks) do
     context = Macro.Env.location(__ENV__)
-
-    escaped_examples =
-      case examples do
-        str when is_binary(str) ->
-          file_extension =
-            str
-            |> Path.extname()
-            |> String.downcase()
-
-          case file_extension do
-            ext when ext in [".md", ".markdown", ".csv"] ->
-              str
-              |> Parser.parse_file_path_examples(context)
-              |> Macro.escape()
-
-            _ ->
-              str
-              |> Parser.parse_examples(context)
-              |> Macro.escape()
-          end
-
-        list when is_list(list) ->
-          list
-          |> Parser.parse_examples(context)
-          |> Macro.escape()
-
-        already_escaped when is_tuple(already_escaped) ->
-          already_escaped
-      end
+    escaped_examples = escape_examples(examples, context)
 
     quote location: :keep do
       for {example, index} <- Enum.with_index(unquote(escaped_examples)) do
         for {key, val} <- example do
           @tag [{key, val}]
         end
 
-        custom_description =
-          example[:test_desc] || example[:test_description] || example[:description] || example[:Description]
-
-        un_truncated_name =
-          case custom_description do
-            nil -> "#{unquote(test_name)} (#{inspect(example)})"
-            test_name -> "#{unquote(test_name)} - #{test_name}"
-          end
-
-        full_test_name =
-          cond do
-            String.length(un_truncated_name) <= 212 -> un_truncated_name
-            is_nil(custom_description) -> "#{unquote(test_name)} row #{index}"
-            true -> String.slice(un_truncated_name, 0, 212)
-          end
+        unquoted_test_name = unquote(test_name)
+        full_test_name = ParameterizedTest.Parser.full_test_name(unquoted_test_name, example, index, 212)
 
         @tag param_test: true
         test "#{full_test_name}", unquote(context_ast) do
@@ -147,4 +121,77 @@ defmodule ParameterizedTest do
       end
     end
   end
+
+  if Code.ensure_loaded?(Wallaby) do
+    @doc """
+    Defines Wallaby feature tests that use your parameters or example data.
+
+    This is to the Wallaby `feature` macro as `param_test` is to `test`.
+
+    Use it like this:
+
+        param_feature \"supports Wallaby tests\",
+                      \"\"\"
+                      | text     | url                  |
+                      |----------|----------------------|
+                      | \"GitHub\" | \"https://github.com\" |
+                      | \"Google\" | \"https://google.com\" |
+                      \"\"\",
+                      %{session: session, text: text, url: url} do
+          session
+          |> visit(url)
+          |> assert_has(Wallaby.Query.text(text, minimum: 1))
+        end
+    """
+    defmacro param_feature(test_name, examples, context_ast \\ %{}, blocks) do
+      context = Macro.Env.location(__ENV__)
+      escaped_examples = escape_examples(examples, context)
+
+      quote location: :keep do
+        for {example, index} <- Enum.with_index(unquote(escaped_examples)) do
+          for {key, val} <- example do
+            @tag [{key, val}]
+          end
+
+          unquoted_test_name = unquote(test_name)
+          @full_test_name ParameterizedTest.Parser.full_test_name(unquoted_test_name, example, index, 212)
+
+          @tag param_test: true
+          feature "#{@full_test_name}", unquote(context_ast) do
+            unquote(blocks)
+          end
+        end
+      end
+    end
+  end
+
+  defp escape_examples(examples, context) do
+    case examples do
+      str when is_binary(str) ->
+        file_extension =
+          str
+          |> Path.extname()
+          |> String.downcase()
+
+        case file_extension do
+          ext when ext in [".md", ".markdown", ".csv"] ->
+            str
+            |> Parser.parse_file_path_examples(context)
+            |> Macro.escape()
+
+          _ ->
+            str
+            |> Parser.parse_examples(context)
+            |> Macro.escape()
+        end
+
+      list when is_list(list) ->
+        list
+        |> Parser.parse_examples(context)
+        |> Macro.escape()
+
+      already_escaped when is_tuple(already_escaped) ->
+        already_escaped
+    end
+  end
 end

lib/parameterized_test/parser.ex

@@ -1,6 +1,5 @@
 defmodule ParameterizedTest.Parser do
   @moduledoc false
-
   @typep context :: [{:line, integer} | {:file, String.t()}]
 
   @spec parse_examples(String.t() | list, context()) :: [map()]
@@ -28,6 +27,41 @@ defmodule ParameterizedTest.Parser do
     end
   end
 
+  @spec parse_file_path_examples(String.t(), context()) :: [map()]
+  def parse_file_path_examples(path, context) do
+    file = File.read!(path)
+
+    case path |> Path.extname() |> String.downcase() do
+      md when md in [".md", ".markdown"] -> parse_examples(file, context)
+      ".csv" -> parse_csv_file(file, context)
+      ".tsv" -> parse_tsv_file(file, context)
+      _ -> raise "Unsupported file extension for parameterized tests #{path} #{file_meta(context)}"
+    end
+  end
+
+  @spec full_test_name(String.t(), map(), integer, integer) :: String.t()
+  def full_test_name(original_test_name, example, row_index, max_chars) do
+    custom_description = description(example)
+
+    un_truncated_name =
+      case custom_description do
+        nil -> "#{original_test_name} (#{inspect(example)})"
+        desc -> "#{original_test_name} - #{desc}"
+      end
+
+    cond do
+      String.length(un_truncated_name) <= max_chars -> un_truncated_name
+      is_nil(custom_description) -> "#{original_test_name} row #{row_index}"
+      true -> String.slice(un_truncated_name, 0, max_chars)
+    end
+  end
+
+  defp description(%{test_description: desc}), do: desc
+  defp description(%{test_desc: desc}), do: desc
+  defp description(%{description: desc}), do: desc
+  defp description(%{Description: desc}), do: desc
+  defp description(_), do: nil
+
   defp parse_hand_rolled_table(evaled_table, context) do
     parsed_table = Enum.map(evaled_table, &Map.new/1)
 
@@ -45,18 +79,6 @@ defmodule ParameterizedTest.Parser do
     parsed_table
   end
 
-  @spec parse_file_path_examples(String.t(), context()) :: [map()]
-  def parse_file_path_examples(path, context) do
-    file = File.read!(path)
-
-    case path |> Path.extname() |> String.downcase() do
-      md when md in [".md", ".markdown"] -> parse_examples(file, context)
-      ".csv" -> parse_csv_file(file, context)
-      ".tsv" -> parse_tsv_file(file, context)
-      _ -> raise "Unsupported file extension for parameterized tests #{path} #{file_meta(context)}"
-    end
-  end
-
   defp parse_csv_file(file, context) do
     file
     |> ParameterizedTest.CsvParser.parse_string(skip_headers: false)

mix.exs

@@ -6,7 +6,7 @@ defmodule ParameterizedTest.MixProject do
   def project do
     [
       app: :parameterized_test,
-      version: "0.3.1",
+      version: "0.4.0",
       elixir: "~> 1.14",
       elixirc_paths: elixirc_paths(Mix.env()),
       start_permanent: Mix.env() == :prod,
@@ -77,6 +77,8 @@ defmodule ParameterizedTest.MixProject do
   defp deps do
     List.flatten(
       [
+        # Optional: supports doing parameterization over Wallaby `feature` tests
+        {:wallaby, ">= 0.0.0", optional: true},
         {:nimble_csv, "~> 1.1"},
         {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},