Fluffy
Phoenix feature tests. Three drivers, one Playwright-shaped API.
Fluffy tests Phoenix pages and LiveViews directly, or uses a real browser when needed. Fluffy's behavior is checked against a real browser to verify that tests run without a browser behave consistently. See the capability matrix for supported behavior and differences.
creature_row =
by_role(:table, name: "Hagrid's creatures")
|> by_role(:row)
|> filter(has: by_text("Fluffy", exact: true))
start_session(:phoenix)
|> visit("/creatures")
|> click(by_role(creature_row, :button, name: "Play flute"))
|> assert(visible(by_role(creature_row, :cell, name: "Asleep")))
This example assumes the imports and test setup below. Locators are reusable queries: find Fluffy's row in the "Hagrid's creatures" table and scope both the action and the assertion to it.
HTML behind this example
<h1 id="guards-heading">Hagrid's creatures</h1>
<table aria-labelledby="guards-heading">
<thead>
<tr><th>Creature</th><th>State</th><th>Actions</th></tr>
</thead>
<tbody>
<tr>
<td>Norbert</td>
<td>Awake</td>
<td>
<form method="post" action="/creatures">
<input type="hidden" name="creature" value="norbert">
<button name="action" value="feed">Feed dragon</button>
</form>
</td>
</tr>
<tr>
<td>Fluffy</td>
<td>Awake</td>
<td>
<form method="post" action="/creatures">
<input type="hidden" name="creature" value="fluffy">
<button name="action" value="flute">Play flute</button>
</form>
</td>
</tr>
</tbody>
</table>
Getting started
Follow Installation and runtime for the dependency, endpoint, browser, and sandbox configuration.
Add use Fluffy.Case after your ConnCase (or use ExUnit.Case), then import the
native locator API's helpers:
use MyAppWeb.ConnCase, async: true
use Fluffy.Case
use Fluffy.Assert
import Fluffy
import Fluffy.Locator
Start with start_session(:phoenix) for in-process Static and LiveView tests.
Use start_session(:playwright) when a test needs a real browser. See
Installation and runtime for Playwright and Ecto sandbox
setup, then Usage for writing tests and starting a session per test.
Coming from PhoenixTest
Replace import PhoenixTest with import Fluffy.PhoenixTest, after use Fluffy.Case.
Existing pipelines keep familiar helpers such as fill_in, click_button, and
assert_has, and their prepared connections:
use Fluffy.Case
import Fluffy.PhoenixTest
# In a test, with the ConnCase's conn:
conn
|> visit("/creatures/new")
|> fill_in("Name", with: "Basilisk")
|> click_button("Register")
|> assert_has("#notice", text: "Creature registered")
|> assert_path("/creatures")
The facade makes Fluffy mostly a drop-in replacement for supported tests, including
browser tests. You also get automatic waiting for LiveView actions and assertions,
automatic LiveView connection waiting in browser tests, and LiveView tests that see
the whole page, including the root layout, live_title updates, and portal content.
Use the facade import on its own. The migration guide shows complete setup, the same helpers with Playwright, and compatibility boundaries. Adopting the native locator API is optional.
For native tests, choose an assertion vocabulary:
use Fluffy.Assert or import Fluffy.Expect.
Beyond page interactions
Capture downloads, open new tabs, handle dialogs, and observe network events with Fluffy's event API. Register a wait before an action, then await a value. Predicates select events; ordinary ExUnit assertions inspect their metadata. See Events and pages for examples and the Capability matrix for what each backend supports.
Guides
- Installation and runtime — endpoint, browser, Ecto sandbox setup, and usage rules for coding agents
- Usage — your first test, backend choice, and a shared test case
- Locators and frames — finding elements and reaching into iframes
- Actions and waiting — actions, waiting, uploads, and controlling time
- Assertions — imported
assert/refuteandexpectvocabularies compared, visibility, and page assertions - Debugging and native access — failures, browser diagnostics, and the native escape hatch
- Events and pages — tabs, windows, iframe limitations, downloads, navigation, dialogs, and network events
- Coming from PhoenixTest — an alternate starting point for existing PhoenixTest suites
- Upgrading to 0.9 — what a 0.8 suite must change
- Capability matrix — backend differences and limitations
See CONTRIBUTING.md for developing Fluffy itself.
License
Fluffy is released under the MIT License.