Run feature tests in an actual browser, using PhoenixTest and Playwright.

defmodule Features.RegisterTest do
  use PhoenixTest.Playwright.Case,
    async: true,                         # async with Ecto sandbox
    parameterize: [                      # run in multiple browsers in parallel
      %{browser_pool: :chromium},
      %{browser_pool: :firefox}
    ]

  @tag trace: :open                      # replay in interactive viewer
  test "register", %{conn: conn} do
    conn
    |> visit(~p"/")
    |> click_link("Register")
    |> fill_in("Email", with: "f@ftes.de")
    |> click_button("Create an account")
    |> assert_has(".error", text: "required")
    |> screenshot("error.png", full_page: true)
  end
end

Please get in touch with feedback of any shape and size.

Enjoy! Freddy.

P.S. Looking for a standalone Playwright client? See PlaywrightEx.

Getting started

1. Add dependency

    # mix.exs
    {:phoenix_test_playwright, "~> 0.9", only: :test, runtime: false}

2. Install playwright and browser

    npm --prefix assets i -D playwright
    npm --prefix assets exec -- playwright install chromium --with-deps

3. Config

    # config/test.exs
    config :phoenix_test, otp_app: :your_app
    config :your_app, YourAppWeb.Endpoint, server: true

4. Runtime config

    # test/test_helpers.exs
    {:ok, _} = PhoenixTest.Playwright.Supervisor.start_link()
    Application.put_env(:phoenix_test, :base_url, YourAppWeb.Endpoint.url()

5. Use in test

    defmodule MyTest do
      use PhoenixTest.Playwright.Case, async: true
   
      # `conn` isn't a `Plug.Conn` but a Playwright session.
      # We use the name `conn` anyway so you can easily switch `PhoenixTest` drivers.
      test "in browser", %{conn: conn} do
        conn
        |> visit(~p"/")
        |> unwrap(&Frame.evaluate(&1.frame_id, "console.log('Hey')"))

Configuration

# config/test.ex
config :phoenix_test,
  otp_app: :your_app,
  playwright: [
    browser_pool: :chromium_pool,
    browser_pools: [
      [id: :chromium_pool, browser: :chromium],
      [id: :firefox_pool, browser: :firefox]
    ],
    js_logger: false,
    browser_launch_timeout: 10_000
  ]

See PhoenixTest.Playwright.Config for more details.

You can override some options in your test:

defmodule DebuggingFeatureTest do
  use PhoenixTest.Playwright.Case,
    async: true,
    # Launch new browser for this test suite with custom options below
    browser_pool: :nil,
    # Show browser and pause 1 second between every interaction
    headless: false,
    slow_mo: :timer.seconds(1)

Traces

Playwright traces record a full browser history, including 'user' interaction, browser console, network transfers etc. Traces can be explored in an interactive viewer for debugging purposes.

Manually

@tag trace: :open
test "record a trace and open it automatically in the viewer" do

Automatically for failed tests in CI

# config/test.exs
config :phoenix_test, playwright: [trace: System.get_env("PW_TRACE", "false") in ~w(t true)]

# .github/workflows/elixir.yml
run: "mix test || if [[ $? = 2 ]]; then PW_TRACE=true mix test --failed; else false; fi"

Screenshots

Manually

|> visit(~p"/")
|> screenshot("home.png")    # captures entire page by default, not just viewport

Automatically for failed tests in CI

# config/test.exs
config :phoenix_test, playwright: [screenshot: System.get_env("PW_SCREENSHOT", "false") in ~w(t true)]

# .github/workflows/elixir.yml
run: "mix test || if [[ $? = 2 ]]; then PW_SCREENSHOT=true mix test --failed; else false; fi"

Emails

If you want to verify the HTML of sent emails in your feature tests, consider using Plug.Swoosh.MailboxPreview. The iframe used to render the email HTML body makes this slightly tricky:

|> visit(~p"/dev/mailbox")
|> click_link("Confirmation instructions")
|> within("iframe >> internal:control=enter-frame", fn conn ->
  conn
  |> click_link("Confirm account")
  |> click_button("Confirm my account")
  |> assert_has("#flash-info", text: "User confirmed")

For a full example see ftes/phoenix_test_playwright_example/tree/phoenix-1.8.

Common problems

Test failure in CI (timeout)

• Limit concurrency: config :phoenix_test, playwright: [browser_pools: [[size: 1]]] or mix test --max-cases 1 for GitHub CI shared runners
• Increase timemout: config :phoenix_test, playwright: [timeout: :timer.seconds(4)]
• More compute power: e.g. x64 8-core GitHub runner

LiveView not connected

|> visit(~p"/")
|> assert_has("body .phx-connected")
# now continue, playwright has waited for LiveView to connect

LiveComponent not connected

<div id="my-component" data-connected={connected?(@socket)}`>

|> visit(~p"/")
|> assert_has("#my-component[data-connected]")
# now continue, playwright has waited for LiveComponent to connect

Ecto SQL.Sandbox

defmodule MyTest do
  use PhoenixTest.Playwright.Case, async: true

PhoenixTest.Playwright.Case automatically takes care of this. It starts the sandbox under a separate process than your test and uses ExUnit.Callbacks.on_exit/1 to ensure the sandbox is shut down afterward. It also sends a User-Agent header with the Phoenix.Ecto.SQL.Sandbox.html.metadata_for/3 your Ecto repos. This allows the sandbox to be shared with the LiveView and other processes which need to use the database inside the same transaction as the test. It also allows for concurrent browser tests.

Ownership errors with LiveViews

Unlike Phoenix.LiveViewTest, which controls the lifecycle of LiveView processes being tested, Playwright tests may end while such processes are still using the sandbox.

In that case, you may encounter ownership errors like:

** (DBConnection.OwnershipError) cannot find owner for ...

To prevent this, the ecto_sandbox_stop_owner_delay option allows you to delay the sandbox owner's shutdown, giving LiveViews and other processes time to close their database connections. The delay happens during ExUnit.Callbacks.on_exit/1, which blocks the running of the next test, so it affects test runtime as if it were a Process.sleep/1 at the end of your test.

So you probably want to use as small a delay as you can, and only for the tests that need it, using @tag (or @describetag or @moduletag) like:

@tag ecto_sandbox_stop_owner_delay: 100 # 100ms
test "does something" do
  # ...
end

If you want to set a global default, you can:

# config/test.exs
config :phoenix_test, playwright: [
  ecto_sandbox_stop_owner_delay: 50  # 50ms
]

For more details on LiveView and Ecto integration, see the advanced set up instructions:

• with LiveViews
• with Channels

Missing Playwright features

This module includes functions that are not part of the PhoenixTest protocol, e.g. screenshot/3 and click_link/4.

But it does not wrap the entire Playwright API, which is quite large. You should be able to add any missing functionality yourself using PhoenixTest.unwrap/2, Frame, Selector, and the Playwright code.

If you think others might benefit, please open a PR.

Here is some inspiration:

def choose_styled_radio_with_hidden_input_button(conn, label, opts \\ []) do
  opts = Keyword.validate!(opts, exact: true)
  PhoenixTest.Playwright.click(conn, PlaywrightEx.Selector.text(label, opts))
end

defp assert_a11y(conn) do
  PlaywrightEx.Frame.evaluate(conn.frame_id, expression: A11yAudit.JS.axe_core(), timeout: @timeout)
  {:ok, json} = PlaywrightEx.Frame.evaluate(conn.frame_id, expression: "axe.run()", timeout: @timeout)
  results = A11yAudit.Results.from_json(json)
  A11yAudit.Assertions.assert_no_violations(results)

  conn
end

defp within_iframe(conn, selector \\ "iframe", fun) when is_function(fun, 1) do
  within(conn, "#{selector} >> internal:control=enter-frame", fun)
end