e2e-entity-suite

name	e2e-entity-suite
description	Run a comprehensive E2E browser test suite for a newly scaffolded Goravel entity. Tests navigation, CRUD operations, search, filters, row actions, form validation, FK dropdowns, and cross-entity integration using Playwright MCP.
argument-hint	[EntityName] [base-url]
allowed-tools	Read, Grep, Glob, Bash, mcp__playwright__*

E2E Entity Test Suite (Playwright MCP)

Agent: Blessings Phiri — Senior QA & Reliability Engineer

Run the complete E2E test suite for $ARGUMENTS.

Prerequisites

• Dev server running: go run . (backend) + pnpm dev (Vite frontend)
• Dev database migrated: go run . artisan migrate
• Seed data exists: Run /fake-data skill first, then go run . artisan db:seed --seeder=EntitySeeder to populate 25+ records. Without seed data, sorting, pagination, and filter tests are meaningless.
• Playwright MCP configured in project .claude.json
• Backend CRUD tests passing before UI testing

Pre-Flight: Verify Seed Data

Before starting browser tests, verify the entity has sufficient data:

# Check record count via API (should return 25+ records)
# Or use the browser to navigate to the page and check the stats card / total count

If the page shows 0 records or the table is empty:

1. Run /fake-data EntityName to create the seeder
2. Run go run . artisan db:seed --seeder=EntitySeeder
3. Refresh the page

Test Protocol

For each test: execute the action, inspect with browser_snapshot, record PASS/FAIL, and note any issues.

Use browser_snapshot (accessibility tree) for assertions — it's faster and more reliable than screenshots.

---

Phase 1: Login & Setup

Test 1.1: Login

1. browser_navigate → http://localhost:5173/login
2. browser_snapshot → find email/password fields
3. browser_type → email field with admin credentials
4. browser_type → password field
5. browser_click → Sign In button
6. browser_wait_for → dashboard or admin page loads
7. browser_snapshot → verify logged in (sidebar visible, user name in header)

PASS criteria: Redirected to admin area, sidebar navigation visible.

---

Phase 2: Navigation

Test 2.1: Sidebar Navigation Entry

1. browser_snapshot → find entity nav item in sidebar
2. Verify: entity appears in correct position with icon
3. browser_click → entity nav item
4. browser_wait_for → page title text
5. browser_snapshot → verify URL is /admin/entity-names

PASS criteria: Nav item visible, click navigates to correct URL.

Test 2.2: Page Load & Structure

1. browser_snapshot → verify page structure:
   - Page title (from i18n, NOT raw key like "page.title")
   - "Add entity" button
   - Stats cards (if enabled)
   - Filter tabs (All, Active, Inactive, etc.)
   - Data table with column headers
   - Pagination or record count

PASS criteria: All structural elements present, no raw i18n keys visible.

Watch for:

• i18n keys rendered as literals (e.g., page.title instead of "Authors")
• Missing stats cards (backend StatsBuilder not configured)
• Empty table (dev DB not seeded or migrations not run)

---

Phase 3: Stats & Filters

Test 3.1: Stats Cards

1. browser_snapshot → find stats cards
2. Verify: total count matches table row count
3. Verify: status-specific counts (active, inactive) are numbers

PASS criteria: Stats cards display with numeric values.

Test 3.2: Filter Tabs

1. browser_snapshot → find filter tab buttons (All, Active, Inactive, etc.)
2. browser_click → "Inactive" tab (or a non-default filter)
3. browser_wait_for → table to update
4. browser_snapshot → verify:
   - URL updated with ?status=INACTIVE (or relevant filter param)
   - Table shows only matching records (or "No results" message)
   - Active tab is visually highlighted
5. browser_click → "All" tab to reset
6. browser_snapshot → verify all records shown again

PASS criteria: Filter tabs update URL, table contents change accordingly.

Watch for:

• Filter not appending query param to URL
• Table not refreshing after filter change
• "All" tab not clearing the filter

---

Phase 4: Create Operation

Test 4.1: Open Create Form

1. browser_click → "Add entity" button
2. browser_snapshot → verify create form dialog/drawer:
   - Section headers (e.g., "Entity Information", "Contact Details")
   - All field labels with correct text (from i18n)
   - Required field indicators (*)
   - Input types match field types (text, email, date, number, textarea, select)
   - Submit/Save button

PASS criteria: Form opens with all expected fields and labels.

Test 4.2: Fill and Submit Create Form

1. Fill all required fields with valid test data
2. Fill optional fields (at least one date, one nullable text)
3. For enum/status fields: browser_click → Select, choose an option
4. browser_click → Submit/Save button
5. browser_wait_for → success toast message (e.g., "created successfully")
6. browser_snapshot → verify:
   - Form closed/dismissed
   - New record appears in table
   - Stats updated (total count incremented)

PASS criteria: Record created, toast shown, table updated.

Watch for:

• Empty string date error: if submit fails with 500, check if nullable date/numeric fields send "" instead of null
• snake_case binding failure: if all fields are empty after creation, check if API request uses camelCase instead of snake_case keys
• Missing dev DB migration: if submit returns 500 "relation does not exist", run go run . artisan migrate

Test 4.3: Verify Created Record

1. browser_snapshot → find the newly created record in table
2. Verify: all visible columns show correct data
3. Verify: status badge displays correctly

PASS criteria: Record visible with correct data in all columns.

---

Phase 5: Detail View

Test 5.1: Open Detail View

1. browser_click → "Open menu" button on the created record's row
2. browser_snapshot → verify action menu: View, Edit, Delete
3. browser_click → "View" option
4. browser_snapshot → verify detail view:
   - All fields displayed with labels
   - Status shown as badge
   - Nullable empty fields show "Not specified" (or equivalent)
   - Metadata section (ID, Created, Last Updated)
   - Dates formatted correctly

PASS criteria: Detail view shows all fields with proper formatting.

Watch for:

• Float precision: price/decimal fields showing 23.989999771118164 instead of 23.99
• Raw i18n keys instead of translated labels
• Missing metadata section

Test 5.2: Close Detail View

1. browser_press_key → Escape (or click close button)
2. browser_snapshot → verify detail view closed, table visible again

---

Phase 6: Edit Operation

Test 6.1: Open Edit Form

1. browser_click → "Open menu" button on the record's row
2. browser_click → "Edit" option
3. browser_snapshot → verify edit form:
   - All fields pre-populated with current values
   - Same fields as create form
   - Metadata section present (ID, Created, Updated)
   - Status dropdown shows current value

PASS criteria: Form opens pre-populated with correct data.

Watch for:

• Float precision in inputs: price field showing 23.989999771118164
• Date fields not formatted as YYYY-MM-DD
• FK dropdown showing "Select..." instead of current value (expected for legacy records without FK set)

Test 6.2: Modify and Save

1. Clear and modify at least one required field
2. Change status dropdown to a different value
3. browser_click → Save/Update button
4. browser_wait_for → success toast (e.g., "updated successfully")
5. browser_snapshot → verify:
   - Form closed
   - Table shows updated values

PASS criteria: Record updated, toast shown, table reflects changes.

---

Phase 7: Table Search

Test 7.1: Search — Match

1. browser_click → search input in the table toolbar
2. browser_type → a known value (e.g., part of the created record's name)
3. browser_wait_for → table to filter
4. browser_snapshot → verify:
   - Table shows only matching records
   - Result count updated

PASS criteria: Search returns matching records.

Test 7.2: Search — No Match

1. Clear search field
2. browser_type → "xyznonexistent12345"
3. browser_wait_for → table to update
4. browser_snapshot → verify:
   - "No results" or empty table message displayed
   - Record count shows 0
5. Clear search field to restore full list

PASS criteria: No results message shown for non-matching query.

---

Phase 8: Column Sorting

Requires: 25+ seeded records (run /fake-data first)

Test 8.1: Sort by Primary Column (Ascending)

1. browser_snapshot → note the current first row's primary field value (e.g., name)
2. browser_click → sortable column header (e.g., "Name" or primary field)
3. browser_wait_for → table to refresh
4. browser_snapshot → verify:
   - Sort indicator (arrow) appears on the clicked column
   - First row shows the alphabetically/numerically lowest value
   - Rows are in ascending order (compare first 3-5 rows)
   - URL may update with ?sort=field&direction=ASC

PASS criteria: Column sorts ascending, sort indicator visible.

Test 8.2: Sort by Primary Column (Descending)

1. browser_click → same column header again (toggle to descending)
2. browser_wait_for → table to refresh
3. browser_snapshot → verify:
   - Sort indicator shows descending direction
   - First row shows the alphabetically/numerically highest value
   - Order is reversed from ascending

PASS criteria: Column sorts descending on second click.

Test 8.3: Sort by Date Column

1. browser_click → "Created" column header (or another date column)
2. browser_wait_for → table to refresh
3. browser_snapshot → verify:
   - Dates are in chronological order
   - Sort indicator on date column

PASS criteria: Date column sorts correctly.

Watch for:

• Sort not working → check column definition has sortable: true
• Sort indicator missing → check CrudPage column rendering
• Records don't change order → check API handles sort and direction query params

---

Phase 9: Pagination

Requires: 25+ seeded records (more than one page worth)

Test 9.1: Verify Pagination Controls

1. browser_navigate → /admin/entity-names (reset to first page)
2. browser_snapshot → verify:
   - Pagination controls visible (page numbers or Next/Previous buttons)
   - Current page highlighted (page 1)
   - Total record count shown (e.g., "Showing 1-10 of 30")
   - Table shows correct number of rows per page (typically 10)

PASS criteria: Pagination controls present with correct counts.

Test 9.2: Navigate to Next Page

1. browser_click → "Next" button or page 2
2. browser_wait_for → table to refresh
3. browser_snapshot → verify:
   - Table shows different records than page 1
   - Current page indicator updated to page 2
   - URL updated with ?page=2
   - "Previous" button now enabled

PASS criteria: Second page shows different records, page indicator updated.

Test 9.3: Navigate Back to First Page

1. browser_click → "Previous" button or page 1
2. browser_wait_for → table to refresh
3. browser_snapshot → verify:
   - Original first-page records displayed
   - Page indicator back to 1

PASS criteria: First page restored correctly.

Watch for:

• No pagination shown → table has fewer records than page size (need more seed data)
• Page 2 shows same records → API not handling page query param
• Total count wrong → stats not refreshing with pagination

---

Phase 10: Global Search (CMD+K)

Test 10.1: Open Global Search

1. browser_press_key → Meta+k
2. browser_snapshot → verify search dialog:
   - Search input with placeholder
   - Quick access section showing entity type (if user has permission)

Test 10.2: Search for Entity

1. browser_type → search query matching the created record
2. browser_wait_for → search results (or short delay)
3. browser_snapshot → verify:
   - Results include the entity with correct type badge
   - Title and subtitle display correctly
   - Entity type badge has correct color
4. browser_press_key → Escape to close

PASS criteria: Entity appears in global search with correct badge and data.

Watch for:

• Entity not appearing → check search_controller.go has the search method and permission check
• Missing type badge → check search_config.tsx has the entity type in SEARCH_ENTITIES
• Empty results → check entity service has WithSearchFields configured

---

Phase 11: Row Actions

Test 11.1: Action Menu

1. browser_click → "Open menu" (three dots) on a table row
2. browser_snapshot → verify menu items:
   - "View" option
   - "Edit" option
   - Separator
   - "Delete" option (in destructive/red style)
3. browser_press_key → Escape to close menu

PASS criteria: All action menu items present.

Test 11.2: Delete — Cancel

1. browser_click → "Open menu" on a row
2. browser_click → "Delete" option
3. browser_handle_dialog → accept: false (Cancel the confirmation)
4. browser_snapshot → verify record still in table (not deleted)

PASS criteria: Cancel prevents deletion, record remains.

Test 11.3: Delete — Confirm (optional, use test record)

Only run this on a test record you intend to discard:

1. browser_click → "Open menu" on the test row
2. browser_click → "Delete" option
3. browser_handle_dialog → accept: true (Confirm deletion)
4. browser_wait_for → table to update
5. browser_snapshot → verify:
   - Record removed from table
   - Stats count decremented
   - Success toast or table refresh

PASS criteria: Record deleted, table and stats updated.

---

Phase 12: Cross-Entity Integration (Conditional)

Skip this phase if the entity is NOT referenced as a foreign key by another entity. Only run when another entity has an FK dropdown pointing to this one (e.g., Author → Book's author dropdown).

Test 12.1: FK Dropdown in Related Entity

1. browser_navigate → /admin/related-entity (e.g., /admin/books)
2. browser_click → "Add" button to open create form
3. browser_snapshot → verify FK field is a dropdown (Select), NOT a text input
4. browser_click → the FK dropdown
5. browser_snapshot → verify:
   - Options load from API (entity names appear in dropdown)
   - The entity created in Phase 4 appears as an option
6. browser_press_key → Escape to close

PASS criteria: FK dropdown loads related entity records.

Test 12.2: FK Dropdown in Edit Form

1. Navigate to related entity list, open edit form for an existing record
2. browser_snapshot → verify FK dropdown:
   - Present as Select (not text input)
   - Pre-selected with current FK value (if set)
   - Or shows "Select..." placeholder (if FK is null for legacy records)

PASS criteria: FK dropdown present and functional in edit form.

Watch for:

• Dropdown shows "Select..." for all records → legacy records have null FK (expected)
• Dropdown falls back to text input → API returned empty array (check /api/entity-names endpoint)
• API returns first_name but JS reads firstName → check model JSON tags match

---

Phase 13: Responsive Layout (Optional)

Test 13.1: Mobile View

1. browser_resize → { width: 375, height: 812 }
2. browser_snapshot → verify:
   - Mobile columns render (compact layout)
   - Sidebar collapsed to hamburger menu
   - Table is scrollable or stacked
3. browser_resize → { width: 1280, height: 720 } (restore desktop)

---

Phase 14: Console & Network Check

Test 14.1: Console Errors

1. browser_console_messages → level: "error"
2. Verify: no React errors, no 404/500 errors, no i18n missing key warnings

Test 14.2: Network Failures

1. browser_network_requests → includeStatic: false
2. Verify: no failed API calls (4xx, 5xx status codes)

---

Bug Watch Checklist

These are known issues to specifically check for during testing:

Bug	Symptom	Root Cause	Fix
Nullable field ""	500 on create/edit with empty date/numeric	Empty string sent instead of null	Use || null in form requestData
Float precision	Price shows 23.989999	Raw float64 from JSON	Use .toFixed(2) in display
Missing dev migration	500 "relation does not exist"	Dev DB not migrated	Run go run . artisan migrate
Snake_case binding	All fields empty after create	camelCase keys in request body	Convert to snake_case in requestData
Search not working	Entity missing from CMD+K	Missing search method/permission	Add to search_controller.go + search_config.tsx
FK dropdown empty	Text input instead of Select	API returns empty array	Check /api/entity-names returns data
i18n raw keys	"page.title" shown literally	Namespace not registered	Add to locales/index.ts
Filter not working	Tab click does nothing	Missing URL query param handling	Check filter config and API param support

---

Test Report Format

After completing all phases, produce a summary:

## E2E Test Report: [EntityName]

### Environment
- URL: http://localhost:5173
- Date: YYYY-MM-DD
- Browser: Chromium (Playwright MCP)

### Results

| # | Test | Result | Notes |
|---|------|--------|-------|
| 1.1 | Login | PASS/FAIL | |
| 2.1 | Sidebar Navigation | PASS/FAIL | |
| 2.2 | Page Load & Structure | PASS/FAIL | |
| 3.1 | Stats Cards | PASS/FAIL | |
| 3.2 | Filter Tabs | PASS/FAIL | |
| 4.1 | Open Create Form | PASS/FAIL | |
| 4.2 | Create Record | PASS/FAIL | |
| 4.3 | Verify Created Record | PASS/FAIL | |
| 5.1 | Detail View | PASS/FAIL | |
| 5.2 | Close Detail View | PASS/FAIL | |
| 6.1 | Open Edit Form | PASS/FAIL | |
| 6.2 | Edit Record | PASS/FAIL | |
| 7.1 | Table Search (match) | PASS/FAIL | |
| 7.2 | Table Search (no match) | PASS/FAIL | |
| 8.1 | Sort Ascending | PASS/FAIL | |
| 8.2 | Sort Descending | PASS/FAIL | |
| 8.3 | Sort by Date | PASS/FAIL | |
| 9.1 | Pagination Controls | PASS/FAIL | |
| 9.2 | Next Page | PASS/FAIL | |
| 9.3 | Previous Page | PASS/FAIL | |
| 10.1 | Global Search Open | PASS/FAIL | |
| 10.2 | Global Search Results | PASS/FAIL | |
| 11.1 | Row Action Menu | PASS/FAIL | |
| 11.2 | Delete Cancel | PASS/FAIL | |
| 11.3 | Delete Confirm | PASS/FAIL/SKIP | |
| 12.1 | FK Dropdown (create) | PASS/FAIL/N/A | |
| 12.2 | FK Dropdown (edit) | PASS/FAIL/N/A | |
| 13.1 | Mobile Layout | PASS/FAIL/SKIP | |
| 14.1 | Console Errors | PASS/FAIL | |
| 14.2 | Network Failures | PASS/FAIL | |

### Issues Found
1. [Description, severity, suggested fix]

### Bugs Fixed During Testing
1. [What was wrong → what was fixed]

---

Cleanup

After testing:

1. browser_close → Close the browser
2. If test records were created, note whether to keep or remove them

Reference

• Playwright MCP tools guide: /playwright-ui-test skill
• CrudPage component: resources/js/components/Crud/CrudPage.tsx
• Global search: resources/js/components/GlobalSearch.tsx + resources/js/config/search_config.tsx
• Admin layout: resources/js/layouts/Admin.tsx
• Login: resources/js/components/login-form.tsx