SideButton Dashboard Knowledge Pack Files

Agents — QA Test Playbook

Prerequisites

• SideButton server running on localhost:9876
• At least one role enabled in Settings
• Navigate to SPA root first (localhost:9876), then use in-app navigation (direct URL returns 404)

Phase 1: Page Load & Structure

#	Test	Method	Pass Criteria
1.1	Agents page loads	Navigate via sidebar button:has-text("Agents")	"Agents" heading visible, no loading spinner
1.2	Header actions	snapshot banner	"Refresh agents" icon button + "+ Start Agent" button visible
1.3	Empty state	No agents running or completed	.empty-card with "No Agents Running" heading + description + "+ Start Agent" CTA
1.4	Sidebar active state	snapshot sidebar	Agents nav item highlighted
1.5	Refresh button	Click "Refresh agents" icon	SVG gains .spinning class while refreshing, disabled during fetch

Phase 2: Start Agent Modal

#	Test	Method	Pass Criteria
2.1	Open modal (header)	Click "+ Start Agent" in header	[role="dialog"] visible with "Start Agent" heading
2.2	Open modal (empty card)	Click "+ Start Agent" in empty card	Same modal opens
2.3	Role dropdown populated	snapshot modal	Native <select> with all enabled roles listed
2.4	Role dropdown default	snapshot role <select> selected value	May show blank if no role has slug 'se' — verify first option is not pre-selected
2.5	Prompt textarea	snapshot modal	Textarea with placeholder "e.g., Pick issue SCRUM-142..." visible
2.6	Cancel modal	Click "Cancel"	Modal closes, page returns to agent list
2.7	Close via ESC key	Press Escape while modal open	Modal closes
2.8	Close via backdrop	Click .modal-overlay area outside the modal box	Modal closes
2.9	Empty prompt validation	Click "Start Agent" with blank prompt	Toast warning "Please enter a prompt for the agent"; modal stays open
2.10	Start agent	Select role → enter prompt → click "Start Agent"	Modal closes, "Running" section appears with new agent card
2.11	Starting state	Click "Start Agent" while submitting	Button changes to "Starting..." and is disabled (prevents double-submit)

Phase 3: Running Agent States

#	Test	Method	Pass Criteria
3.1	Waiting state	Agent queued but not yet started	.agent-card.waiting — amber left border, amber dot, "Queued {time}" text
3.2	Running state	Agent actively executing	.agent-card.running — green left border, animated green pulse dot, "Started {time} · {duration}"
3.3	Role badge format	snapshot running card	Badge shows uppercased role slug (e.g., SOFTWARE-ENGINEER, QA-AGENT-—-UNIVERSAL-WEB-APP-TESTING)
3.4	Prompt display	snapshot running card	initial_prompt field text shown in .agent-prompt block (only if present)
3.5	Metrics visible (running only)	snapshot running card	Actions count, Tokens (formatted e.g. "12.5K"), Cost ($0.00) in .agent-metrics
3.6	Metrics absent on waiting	snapshot waiting card	No metrics block visible for waiting status agents
3.7	Current task output	snapshot running card	.agent-output block with monospace terminal output (dark background #1e1e2e)
3.8	Auto-poll always active	Wait 10 seconds with no running agents	Page data still refreshes every 5s regardless of running count
3.9	View Log (running)	Click "View Log" on running agent	Navigates to run log detail view for that run_id
3.10	Stop agent	Click "Stop" on running agent	Native confirm() dialog: "Stop this agent?" — on confirm: toast "Agent stopped", agent moves to Completed
3.11	Stop cancel	Click "Stop" → click Cancel in confirm dialog	Agent remains running, no state change

Phase 4: Completed Agents

#	Test	Method	Pass Criteria
4.1	Completed section appears	Agent finishes	"Completed Today ({count})" section visible below Running section
4.2	Success status	Agent status completed	.status-dot.success (solid green), duration + "Completed {time}"
4.3	Failed status	Agent status failed	.agent-card.failed (red left border), .status-dot.failed (solid red), "Error: ..." in result block
4.4	Result summary	snapshot completed card	result_summary shown as "Result: {text}" (success) or "Error: {text}" (failure)
4.5	No result summary	Agent completed with no result	No .agent-result block rendered (conditional render)
4.6	View Log (completed)	Click "View Log" on completed agent	Navigates to run log detail view
4.7	Resend agent	Click "Resend" on completed card	Button shows "Resending..." while in progress; on success toast "Job re-queued"; agent re-appears in Running section
4.8	Resend error	Resend fails (API error)	Toast "Failed to resend: {error}"; button returns to "Resend"
4.9	Today-only scope	Historical agents (prior day)	Not shown — Completed section only includes today's agents

Phase 5: Edge Cases

#	Test	Method	Pass Criteria
5.1	Role badge for skill roles	Start agent with skill-based role (e.g. "SideButton Skills QA")	Badge shows full uppercased slug e.g. SIDEBUTTON-SKILLS-QA
5.2	Section count updates	Running section heading	Shows "Running ({n})" with live count; updates on each poll
5.3	Refresh error toast	Simulate API failure during refresh	Toast "Refresh failed: {error}" in red
5.4	Stop error toast	Stop fails (API error)	Toast "Failed to stop: {error}" in red

Automation Tips

• Role dropdown is native <select>: Use select_option() — values are lowercased, hyphenated role names (em-dashes preserved, e.g. pm-—-portal-chat)
• Role dropdown may show blank by default: selectedRole initializes to 'se' but if no enabled role has that slug, the select renders blank — explicitly select a value before submitting
• ESC closes modal: press_key('Escape') is the most reliable way to close the modal without clicking Cancel
• Backdrop click works: Click .modal-overlay (anywhere outside the white modal box) to dismiss — clicking inside the modal stops propagation
• Polling is always active: Page polls every 5s on mount regardless of running count — do NOT assume metrics are static when no agents are running
• Metrics only visible on running status: waiting agents show no metrics block — only "Queued" time
• waiting is a distinct state: Agents may sit in waiting before running — test for amber dot, not just green

Known Blockers

• Stop uses native confirm(): confirm("Stop this agent?") is a browser-native dialog — cannot be intercepted via snapshot/click. Requires browser dialog event handling or manual test step
• "Starting..." state is transient: The button disabled state during submission is brief — difficult to capture in automation without coordination