Testing
Test admin pages through their real endpoints with tbtop(): forms, actions, modals, tables and gates, asserting on the wire the client receives.
Added in v0.8.0
The testing API ships with tbtop/admin 0.8.0. It lives in the package
itself; there is nothing extra to install.
tbtop(Page::class, $params) visits a page the way the React client does and returns a
PageTester. From there a test narrows to a form, a table or an action, and every call goes
through the page's real endpoints: the panel middleware, the page gate (can()),
authorize() and validation all run. Assertions read the wire — the StructureNode JSON,
table rows and effects the client receives — so a refactor that keeps the screen the same
keeps the tests green.
it('creates a post', function () {
$this->actingAs(User::factory()->create());
tbtop(CreatePostPage::class)
->fill(['title' => 'Hello'])
->submit()
->assertHasNoErrors()
->assertRedirect();
expect(Post::where('title', 'Hello')->exists())->toBeTrue();
});- Pest:
tbtop()is a global function the package autoloads; nothing to register. - PHPUnit:
use Tbtop\Admin\Testing\InteractsWithTbtop;in the test case, then$this->tbtop(Page::class). - Values go out as the client sends them. An enum as its value, a date as ISO 8601 with
its offset, a model as its key, and
submit()posts JSON. So->fill(Post::factory()->make()->only(['title', 'status']))works as is. - No implicit login. The tester acts as whoever
actingAs()set — guests and roles are tested explicitly. - Params are the page path's route parameters; models are fine:
tbtop(EditPostPage::class, ['post' => $post]). A page in several panels takes the panel id as the third argument.
The page
tbtop(EditPostPage::class, ['post' => $post])
->assertOk()
->assertTitle('Edit post')
->assertFieldVisible('title')
->assertFieldHidden('internal_notes') // when()/authorize() kept it off the wire, or hidden()
->assertFieldDisabled('slug')
->assertFieldValue('title', 'Hello') // the form's record()
->assertActionVisible('publish')
->assertActionHidden('delete'); // authorize() dropped itClient-side conditions (hiddenIf, disabledIf) are not evaluated: the tester reads what
the server sends. Rendering, clicks and the client's zod checks belong in browser tests.
Forms
tbtop(CreatePostPage::class)
->form('post') // optional when the page has one form outside modals
->fill(['title' => '', 'sections.0.heading' => 'Intro'])
->submit()
->assertHasErrors(['title' => 'required']);fill() starts from the record the form was prefilled with, so an edit test only names the
fields it changes. A key that is no field of the form fails at once. submit() posts to the
form's onSubmit() handler like Inertia does, then reads the flashed effects or the session
errors; form()->callAction('quickSave') runs a form action with the filled values instead.
Actions and modals
$page = tbtop(PostsIndexPage::class);
$page->callAction('publish', row: $post); // a server action
$page->callAction('create', form: ['title' => 'From modal']) // a modal: opened, filled, submitted
->assertHasNoErrors()
->assertModalClosed();
$page->openAction('edit', $post) // query() runs, nothing submitted yet
->assertFormData(['title' => $post->title])
->fill(['title' => 'Renamed'])
->submit(); // the modal's one action that takes the formA modal with two form actions (Save, Save and close) needs ->callAction('saveAndClose')
on the ModalTester instead of submit(). A url() or custom() action makes no server
call, so calling one fails; assert it with assertActionVisible().
Results
submit() and every call*() return a Result. The two transports — a form's redirect
with flashed effects and session errors, an action's JSON effects and 422 — share one set of
assertions:
| Assertion | Checks |
|---|---|
assertHasErrors(['title' => 'required']) | A failed field; a rule (matched by the message it renders) or the message itself. A list or a string names fields only |
assertHasNoErrors() | No validation errors, and no refusal (any 4xx/5xx but 422) |
assertEffect('setFormData', ['data' => [...]]) / assertNoEffects() | An effect of the closed set, its fields a subset (nested maps too) |
assertNotified('Saved', 'success') | A notify effect |
assertRedirect($url) | A redirect effect, or a form handler that returned a URL |
assertModalClosed() / assertHalted('Not yet') | closeModal / haltModal |
assertTableRefreshed('posts') | refreshTable |
assertForbidden() / assertStatus(422) | The HTTP status |
->response() on any tester returns the raw TestResponse for anything else.
Tables
$posts = tbtop(PostsIndexPage::class)->table('posts'); // name optional with one table
$posts->search('hello')
->filter('status', 'draft')
->sort('created_at', 'desc')
->tab('mine')
->assertCanSeeRecords([$draft])
->assertCanNotSeeRecords([$published])
->assertCell($draft, 'status', 'Draft') // the value as the server formatted it
->assertTotal(1);
$posts->page(2)->perPage(50)->assertCountRecords(3);
$posts->assertTabCount('draft', 4)->assertColumnHidden('secret');search(),filter(),sort(),tab(),page()andperPage()collect the query; rows are fetched on the next assertion. An undeclared filter, tab, column or a column withoutsortable()fails at once instead of quietly returning every row.- Records are a model, a collection, a key or a row; rows match by
_key. assertTotal()needs a length-aware table; withsimplePagination()useassertCountRecords().
$posts->callRowAction('delete', $post)->assertTableRefreshed();
$posts->callBulkAction('publish', [$a, $b])->assertNotified('2 posts published');
$posts->openRowAction('edit', $post)->assertFormData(['title' => $post->title]);
$posts->callAction('create', form: ['title' => 'New']); // a table header actionA row action sends the row the way the table shows it, so the record must be on the current page of rows (search, tab or page to it). After a call the next assertion fetches the rows again.
Gates
$this->actingAs($viewer);
tbtop(SettingsPage::class)->assertForbidden();
tbtop(SettingsPage::class)->table('audit')->assertForbidden();
tbtop(SettingsPage::class)->form('settings')->submit()->assertForbidden();A page that does not render has no wire to read, so the tester sends calls blind: each
endpoint answers on its own, which is how a test proves the gate holds there too. An action
authorize() removes is off the wire: assert it with assertActionHidden().
Generated tests
make:tbtop-resource Post --tests writes tests/Feature/Admin/PostsTest.php on this API:
list (and search), create (and a required field left empty), edit, delete one and a
selection, plus view, restore and force delete, and a policy-refusal case when the flags ask
for them. Records come from the model's factory; without one, the file ends with a helper of
sample values to check. Under --policy a Gate::before returning $this->allowed stands in
for the policy stub, so the cases pass before it is written; the refusal case sets it to
false.
Not covered yet
Live regions, select and relation search and option creation, uploads, inline-editable
cells, reorder, stat and chart data, and MCP tools. Until they land, reach their endpoints
with ->url('relationSearch', 'author_id') and $this->postJson().
Navigation
How the panel menu is built from each page's nav() declaration, and how to configure groups, sections, icons, badges, nesting, extra links, the user menu and the command palette.
Yes / no / any filter
Filter a table on a boolean with three states — yes, no, or don't filter — with Radio::ternary(), or the radio and select filters for custom shapes.