markdown_test

Test the Elixir code in your markdown files!

Monthly Downloads: 10

Programming language: Elixir

License: Apache License 2.0

Tags: Testing    

README

MarkdownTest

Test the Elixir code in your markdown!

Usage

Add :markdown_test as a dependency in your mix.exs file:

# mix.exs

defp deps do
  [
    {:markdown_test, "0.1.2", only: :test}
  ]
end

In any test module, use MarkdownTest to pull in the test_markdown/1 macro and call it for your markdown file:

defmodule MyLibraryTest do
  use MarkdownTest

  test_markdown("README.md")
end

Then add some Elixir code to test in your markdown file.

The format roughly resembles that of a doctest.

In order to be picked up, a code block must be between the following markdown comment tags:

<!--- MARKDOWN_TEST_START -->

...code

<!--- MARKDOWN_TEST_END -->.

Examples

<!--- MARKDOWN_TEST_START -->

iex> 1 + 2
3

<!--- MARKDOWN_TEST_END -->

The expression and expected values can span multiple lines:

<!--- MARKDOWN_TEST_START -->

iex> a = %{cool: :beans}
...> b = %{beans: :cool}
...> Map.merge(a, b)
%{
  cool: :beans,
  beans: :cool
}

<!--- MARKDOWN_TEST_END -->

You can also include any setup code that needs to be run prior to testing the code:

<!--- MARKDOWN_TEST_START -->

defmodule MyModule do
  def add(x, y), do: x + y
end

iex> MyModule.add(1, 2)
3

<!--- MARKDOWN_TEST_END -->

markdown_test will assert that the expression and the expected value match according to Elixir's pattern matching.

Therefore, you can write a test like this:

<!--- MARKDOWN_TEST_START -->

defmodule MyModule do
  def big_result do
    {:ok, List.duplicate("hey", 1000)}
  end
end

iex> MyModule.big_result()
{:ok, ["hey" | _]}

<!--- MARKDOWN_TEST_END -->

If you don't add any assertion code, markdown_test will just verify that the code snippet compiles, like:

<!--- MARKDOWN_TEST_START -->

%{
  this: %{
    "should" => :compile
  }
}

<!--- MARKDOWN_TEST_END -->