View Source Surface.LiveViewTest (surface v0.9.1)

Conveniences for testing Surface components.

Link to this section Summary

Functions

This macro generates ExUnit test cases for catalogue examples.

Compiles Surface code into a new LiveView module.

Registers components that propagates context into its slots.

Render Surface code.

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

Link to this section Functions

Link to this macro

catalogue_test(module_or_all, opts \\ [])

View Source (macro)

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

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

Options

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

examples

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
Link to this macro

compile_surface(code, assigns \\ quote do %{} end)

View Source (macro)

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

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)
Link to this function

register_propagate_context_to_slots(components)

View Source

Registers components that propagates context into its slots.

Link to this macro

render_surface(list)

View Source (macro)

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

Example

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

assert html =~ """
      <a href="/users/1">user</a>
      """
Link to this macro

using_config(component, config, list)

View Source (macro)

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

Example

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

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