Skip to content

Source: tests/e2e/README.md. Edit it there; this page is generated at build time.

Browser tests ​

Playwright specs that drive the Filament admin panel and the public site in a real browser, plus the screenshot run that generates the admin guide.

These complement the Pest tests in tests/Feature rather than replacing them. Pest asserts at the HTTP layer, which cannot see anything Livewire or Alpine does after the page lands — conditional fields, relation-manager modals, drag ordering, the dashboard charts, the theme toggle, live search. That is what lives here.

Running ​

bash
npm run test:e2e        # headless
npm run test:e2e:ui     # interactive
npm run docs:screenshots  # regenerate docs/admin-guide/img/

If php on your PATH isn't the version this project runs on, override it:

bash
E2E_PHP=/opt/homebrew/opt/php@8.4/bin/php npm run test:e2e

Other overrides: E2E_PORT (default 8111), E2E_BASE_URL.

How it fits together ​

FileRole
../../playwright.config.jsPorts, paths, the four projects, and the artisan serve web server.
global-setup.jsRebuilds database/e2e.sqlite from scratch, then seeds it. Runs before the server boots.
auth.setup.jsLogs in once and saves the session to .auth/admin.json. Every admin spec reuses it.
helpers.jsThe resource list every spec iterates, the public-site fixtures, plus locator helpers.
public-*.spec.jsThe public site. Only runs under the public project.
docs-screenshots.spec.jsCaptures the guide's images. Only runs under the docs project.

Four Playwright projects: setup (log in), admin (the /admin specs), public (the public site), docs (screenshots). npm run test:e2e runs setup + admin + public; npm run docs:screenshots runs setup + docs. Keeping docs separate means a normal test run never rewrites files in docs/.

Both npm scripts name their projects explicitly, so a project added to the config but not to the script exists and never runs — which on the terminal is indistinguishable from passing. public also has to be listed in admin's testIgnore, or its specs run twice, the second time against an admin session.

public takes no storageState and does not depend on setup: there is no public login to reuse, and the theme specs need localStorage to start empty.

The public site needs built assets ​

Every public page goes through @vite, which throws outright without public/build/manifest.json — and that directory is gitignored, so a fresh clone or worktree has none. The admin panel ships its own assets and never noticed. global-setup.js therefore runs npm run build when the manifest is missing, and leaves it alone when it is not: a build on every run would be rewriting files in your working tree to produce output it already had.

The consequence for Blade work is the one CLAUDE.md already warns about — a new Tailwind utility class does not exist until npm run build runs, and a public spec asserting on a computed style will fail until it does.

Isolation ​

The suite never touches your development environment. global-setup.js writes a throwaway database/e2e.sqlite, and the server is launched with DB_DATABASE, APP_URL and friends set in its environment — Laravel loads .env immutably, so variables already in the environment win. Your .env and database/database.sqlite are left alone.

Because the database is rebuilt on every run, specs may create and delete records freely.

That last sentence is why artisan serve must keep its --no-reload flag. When a .env file is present and the flag is absent, ServeCommand blanks every variable missing from its $passthroughVariables list before starting the server subprocess — and that list contains no DB_*, no APP_URL, no SESSION_DRIVER. The override would be discarded, the server would fall back to .env, and specs that "create and delete records freely" would be doing it to your own database.

It does not fail that way on every machine, which is what makes it dangerous. ServeCommand reads $_ENV, and a shell-exported variable only lands there when PHP's variables_order includes E. The common CLI default of GPCS leaves $_ENV holding just the .env values, so the override sails through untouched and the suite looks correctly isolated. Build a CI image with EGPCS and the same command quietly points at whatever .env says instead. Verify with two databases whose contents differ rather than trusting a passing run.

Things that will bite you ​

A running npm run dev takes over the suite's assets. It writes public/hot, and while that file exists @vite points every page at the dev server instead of public/build, so the e2e server serves whatever Vite has in memory, not the build global-setup.js checked for. The dev server also has refresh: true, so saving any Blade file during a run full-reloads every open page. A locator resolved before the reload then fails with "Element is not attached to the DOM", which looks like a flaky spec. Stop npm run dev (or leave the views alone) while the suite runs.

Leaving a page before a new upload finishes loading can abort the next goto. settings.spec.js uploads a logo, opens the homepage, then goes back to the admin; about half the runs failed with net::ERR_ABORTED on that last goto, with no reload in the console and a finished load event on the page before it. Waiting for networkidle on the page showing the new image fixed it, 6 of 6. The cause was not pinned down, so if it comes back somewhere else, look there first.

The test login is not a super_admin. The panel requires multi-factor authentication for that role (see AdminPanelProvider), which a browser test cannot complete. Database\Seeders\E2eSeeder creates an e2e_admin role holding every permission individually, so the panel looks identical while staying MFA-free.

AdminFormSchemaTest cannot see a class that was never imported. It scans admin classes for Filament use statements that don't resolve — so a wrong import is caught, but a class referenced with no use statement at all isn't an import and is invisible to it. That is a live failure mode, not a hypothetical: Notification::make() in AffiliateLinksRelationManager with no use Filament\Notifications\Notification resolved to App\Filament\Resources\Products\RelationManagers\Notification, and the only symptom was a table action that opened a Laravel error page inside Filament's modal iframe. Pest was green throughout. Clicking a new action in a browser is the only thing that finds this class of bug.

->native(false) alone is enough to break selectOption(). The known trap is ->searchable(), but a plain non-native select renders a listbox too, and selectOption() fails on it with "element is not a select". Use selectFirstOption() or selectOptionByLabel(), which check tagName === 'SELECT' and branch.

Filament labels need exact matching. Required fields render as Label*, and a password field's reveal toggle is also labelled "…password" — so getByLabel('Password') matches three elements and trips strict mode. Use the field() helper. A regex will not save you here: Playwright only normalizes label whitespace for string matchers, and Filament wraps label text across several lines.

The same whitespace rule bites getByText on the public site. <x-ui.byline> renders By {{ $author->name }} on its own indented line, so the text node is "\n By Jordan Reviewer\n ". getByText('By Jordan Reviewer') matches it; getByText(/^By Jordan Reviewer$/) does not, and fails looking like a missing byline rather than a matcher problem. Regex matchers are handed the raw text — string matchers are the only ones that normalize. Reach for a regex only when you actually want a partial match, and anchor it loosely.

The theme is data-theme on <html>, not a dark class. classList.contains('dark') is false in both themes, which reads as a broken toggle. resources/css/app.css declares a dark variant keyed on html[data-theme='dark'] — Tailwind's class strategy is not in play, and only the toggle's two icons use the variant at all; everything else re-skins through the colour tokens.

Three theme states, and the third one is an absent attribute. No stored choice means no data-theme at all, on purpose: that absence is what lets the CSS fall through to prefers-color-scheme. Drive it with Playwright's colorScheme option (test.use({ colorScheme: 'dark' })) and assert not.toHaveAttribute('data-theme'). Asserting the attribute is also not enough on its own — the whole palette is CSS custom properties, so a token that stopped reacting would still leave the attribute set. Assert a real getComputedStyle(document.body) colour, as public-theme.spec.js does.

The theme toggle is inert until Alpine lands. The pre-paint script in <head> is inline and synchronous, but x-data="themeToggle" comes from the Vite bundle — so a click that arrives first does nothing at all, and the spec fails on the assertion after it. Wait for window.Alpine before clicking.

A rich-editor block with no preview breaks insertion, not just the preview. RichContentCustomBlock::toPreviewHtml() defaults to returning null, but CustomBlockAction base64-encodes the result unguarded (and RichEditorStateCast::set() repeats it on every hydrate), so the default is not a usable default. Every block in app/Filament/Forms/Components/RichEditor/RichContentCustomBlocks/ must return real markup.

Rich-editor blocks are click-to-insert, not only drag-and-drop — the docs describe dragging, which is why this is easy to get wrong in a spec. The buttons are .fi-fo-rich-editor-custom-block-btn; the panel toggle is button[x-on\:click*="customBlocks"] and exists only when customBlocks() is non-empty. The modal's submit button reads Insert, or Save when editing an existing block — never "Submit". The panel also stays open after an insert, so a second insert must check visibility first rather than blindly re-clicking the toggle.

RichContentRenderer::toHtml() sanitizes, and it removes things the x-ui.* components rely on. Inline <svg> is dropped outright, taking every heroicon with it; aria-label and aria-labelledby are stripped while role and tabindex survive; and =/& come back as &#61;/&amp; inside attributes. Harmless in a browser, but a string assertion against rendered block output has to decode first. Widening this means overriding the HtmlSanitizerConfig binding, which affects all rich content — not just blocks.

Select rendering depends on searchable(). A searchable select is a button plus a listbox (getByRole('option')); a plain one is a native <select> (selectOption). The selectFirstOption helper in helpers.js handles both. A searchable multi-select keeps its listbox open between picks.

routes/console.php does not exist during a web request. It is required by the console kernel and nothing else, so app(Schedule::class)->events() is empty in a browser while being fully populated under artisan test — Pest boots in console context. The scheduler page shipped a green "Everything ran on time" banner over an empty table for exactly this reason, with every HTTP test passing. app(Illuminate\Contracts\Console\Kernel::class)->bootstrap() loads it; the browser is the only thing that catches the omission.

Filament 4's compiled CSS contains no Tailwind utilities. public/css/filament/filament/app.css has zero occurrences of .flex, .text-sm, .gap-2 or any other utility class — v4 moved entirely to semantic fi- classes. Utilities written into an admin Blade file are inert, and the panel does not load resources/css/app.css, so npm run build cannot help. Build admin UI out of Filament's own components (<x-filament::callout>, <x-filament::section>, <x-filament::badge>) or a real Filament table.

A custom-data table takes Model|array and nothing else. Table::records() accepts a closure returning rows, but Filament's internal mapper is typed Model|array $record — handing it value objects fails with a TypeError from inside HasRecords::getTableRecords(), not a helpful message. Flatten to arrays at the page boundary and let the column closures take array $record.

A Filament table scrolls sideways before it shrinks. One long value in one column (a scheduled model:prune --model='Fully\Qualified\Class') pushes the rightmost columns out of the viewport with no visual hint they exist. Whatever matters most belongs on the left, and a long string wants shortening at the source — ->wrap() only breaks on spaces.

Wait on the button that goes away, not the one that appears. A pending comment shows both Approve and Reject, so clicking Approve and then waiting for Reject passes at once, before Livewire has saved anything — and the goto that follows aborts the request. The screenshot run captured "Comments (0)" under an approved comment for exactly this reason. Wait for the clicked action to be gone (toHaveCount(0)) instead.

A table's filter panel stays open after Apply. applyFilter() leaves the dropdown over the first rows, so a click on a row action straight after it times out with "subtree intercepts pointer events". Press Escape first. Asserting on a row is fine; only clicks are blocked.

A file upload has to wait for FilePond. Filament renders a plain <input type="file" x-ref="input"> first, and FilePond, loaded after the page, replaces it with its own input.filepond--browser. setInputFiles() on the first one before the swap drops the file with no request and no error, and the spec times out waiting for the upload. It passed on a fast machine and failed on every CI run once the suite had grown. Wait for .filepond--root input.filepond--browser and set the file on that.

Adding coverage for a new resource ​

Add it to RESOURCES in helpers.js. The navigation spec picks it up automatically — sidebar link, index table, and create page. Write a dedicated spec only for behavior beyond that.

A new public content type goes in PUBLIC_PAGES in the same file, which the smoke pass iterates for heading, byline and a whole-page render.

If a new resource is invisible to the tests, its Shield permissions probably haven't been generated. E2eSeeder runs shield:generate --all before assigning permissions, so this should be handled — but the same problem in development needs php artisan shield:generate --all --panel=admin and a re-sync of the role.