This macro generates ExUnit test cases for catalogue examples.

The tests will automatically assert if the example was successfully rendered.

Pay attention that, by default, the generated tests don't test how the components should look like. However, it makes sure the examples are not raising exceptions at runtime, for instance, due to changes in the component's API.

Usage

The catalogue_test/1 macro accepts a single argument which can one of:

• A component module (subject), which will generate tests for all examples/playgrounds found for that component.
• The atom :all, which will generate tests for all examples/playgrounds found for ALL components in the project.

Keep in mind that you should either use individual catalogue_test/1 calls for each component or use :all. Otherwise, you will end up with duplicated tests.

Options

• except - A list of modules that should be excluded. This option only applies when using :all.

Examples

Generating tests for components' examples:

defmodule MyProject.Components.ButtonTest do
  use MyProject.ConnCase, async: true

  catalogue_test MyProject.Components.Button
end

Generating tests for all avaiable components:

defmodule MyProject.Components.CatalogueTest do
  use MyProject.ConnCase, async: true

  catalogue_test :all
end

Generating tests for all avaiable components except MyComponent:

defmodule MyProject.Components.CatalogueTest do
  use MyProject.ConnCase, async: true

  catalogue_test :all, except: [MyComponent]
end

Compiles Surface code into a new LiveView module.

This macro should be used sparingly as it always generates and compiles a new module on-the-fly, which can potentially slow down your test suite.

Its main use is when testing compile-time errors/warnings.

Example

code =
  quote do
    ~F"""
    <KeywordProp prop="some string"/>
    """
  end

message =
  ~S(code:1: invalid value for property "prop". Expected a :keyword, got: "some string".)

assert_raise(CompileError, message, fn ->
  compile_surface(code)
end)

Registers components that propagates context into its slots.

Render Surface code.

Use this macro when testing regular rendering of stateless components or live components that don't require a parent live view during the tests.

For tests depending on the existence of a parent live view, e.g. testing events on live components and its side-effects, you need to use either Phoenix.LiveViewTest.live/2 or Phoenix.LiveViewTest.live_isolated/3.

Example

html =
  render_surface do
    ~F"""
    <Link label="user" to="/users/1" />
    """
  end

assert html =~ """
      <a href="/users/1">user</a>
      """

Wraps a test code so it runs using a custom configuration for a given component.

Tests using this macro should run synchronously. A warning is shown if the test case is configured as async: true.

Example

using_config TextInput, default_class: "default_class" do
  html =
    render_surface do
      ~F"""
      <TextInput/>
      """
    end

  assert html =~ ~r/class="default_class"/
end