README.md

Heyya

Heyya is a utility to help with testing your Phoenix components and live view.

Getting Started

Getting Started

To use Heyya in your Phoenix project, add it to your list of dependencies in mix.exs:

def deps do
  [
    {:heyya, "~> 1.0.0"}
  ]
end

Then, run mix deps.get to install Heyya and its dependencies. Use some case templates provided that make testing easier and more automated.

Examples

In order to show how the different tests can be implemented we have an example Phoenix project in the example project.

Changes of note are:

• Added two example live views that show simple pages.
• Added the Heyya dependency
• Added snapshot component tests that show variants get expected classes and aggregate components combine as expected.
• Added live view tests that show Heyya's full page live view testing utilities. Open a page and surf around.
• Added the /dev/heyya/host route for dev and test environments
• Added a live_component tests that shows stateful component testing with dynamic content without full page data load.

Example Component Snapshot Usage

use Heyya.SnapshotCase

component_snapshot_test "Super Simple H1 Test" do
  assigns = %{}

  ~H"""
  <h1>Testing</h1>
  """
end

To run the snapshot tests, run mix test as usual. This will compare the snapshots to the current rendered output of the components and fail the tests if the snapshots do not match.

If you need to update the snapshots for any reason, you can run HEYYA_OVERRIDE=true mix test to reset the snapshot values to the current rendered output of the components.

Credit:

The initial snapshot code used Snapshy. We have since moved on to inspect the html rather than using snapshy. Thank you to them for the initial implementation.

Example Live View Test

use Heyya.LiveCase
use MyPhoenixWeb.ConnCase

test "widget list with new button", %{conn: conn} do
  start(conn, ~p|/widgets|)
  |> assert_html("Widgets List")
  |> click("a", "New Widgets")
  |> follow(~p|/widgets/new|)
end

Example Live View Snapshot Test

test "/numbers renders the live_view", %{conn: conn} do
  conn
  |> start(~p"/numbers")
  |> assert_matches_snapshot(name: "full_view", selector: "main")
end

That will start a live view test session and assert that the rendered output of the live view matches the snapshot named "full_view" after asserting that there is an element with the selector "main".

This is a very fast way to assert that the live view is rendering the expected output. The default selector is "main" if none is provided, and you will likely want to provide a selector to ensure that the snapshot is only capturing the relevant part of the rendered output.

Example Live Component Test

In order to test a live view component we need a full endpoint. Attach the component host into the Router for test environments (attaching for debug is nice sometimes too).

That can be done like this:

if Enum.member?([:dev, :test], Mix.env()) do
  scope "/dev" do
    pipe_through :browser

    live "/heyya/host", Heyya.LiveComponentHost
  end
end

From then on /dev/heyya/host will host dynamic content with no layout other than a single wrapper div.

  use Heyya.LiveComponentCase
  use ExampleWeb.ConnCase
  use Phoenix.Component

  def render(assigns) do
    ~H"""
    <.live_component module={ExampleWeb.LiveCounterComponent} id="example" />
    """
  end

  test "Test Counter", %{conn: conn} do
    conn
    |> start()
    |> click("button.increment")
    |> assert_html("Counter: 1")
  end

Contributing

We welcome contributions to Heyya! Please see the CONTRIBUTING.md file for guidelines on how to contribute.

License

Heyya is released under the Apache 2.0