Device Groups

Context#

Comprehensive manual QA testing plan for device groups — logical collections of devices used for organizational and reporting purposes. Every device belongs to a group. A special General group exists by default and cannot be edited or deleted. When a custom group is deleted, its devices are automatically reassigned to General.

How to Use This Plan#

• Work through each section sequentially
• For every setting: change it, save, refresh the page, and confirm it persisted
• Mark each item pass/fail as you go
• Pre-requisites: At least 2-3 devices should exist to test linking/reassignment

Key Concepts#

1. Device Groups List Page#

Route: /dashboard/{org}/devices/groups

1.1 Data Table Display#

• Page loads and displays all device groups in a table
• Columns visible:
  • Name — sortable, title variant. Shows lock icon next to "General" group
  • Raised — currency-formatted amount, right-aligned, sortable
  • Devices — device count, right-aligned, sortable
  • Created — formatted date, sortable
  • ID — group identifier
• All column data matches expected values for each group
• Currency formatting is correct (e.g., $1,234.56)
• General group always present in list
• Lock icon visible only on General group row

1.2 Sorting#

• Default sort: Amount Raised (descending)
• Group Name — click to sort alphabetically asc/desc
• Amount Raised — click to sort by raised amount
• Devices — click to sort by device count
• Created Date — click to sort by creation date
• Sorting persists in URL params
• Sort order survives page refresh

1.3 Filtering#

• Amount Raised (range filter):
  • Set min amount → filters correctly
  • Set max amount → filters correctly
  • Set both min and max → range filter works
• Device Count (range filter):
  • Set min device count → filters correctly
  • Set max device count → filters correctly
  • Set both → range filter works
• Combining both filters works correctly
• Clearing filters restores full list
• Filter state persists in URL params

1.4 Search#

• Search by group name — matches correctly (partial match)
• Search by group ID — matches correctly (prefix match)
• Clear search restores full list
• Search works in combination with filters

1.5 Pagination#

• Pagination controls appear when groups exceed page size
• Page size options: 20, 50, 100
• Navigating pages works correctly
• Page state persists in URL

1.6 Mobile Responsive#

• Resize to mobile width — table switches to card view
• Mobile card shows:
  • Group name (with lock icon if General)
  • Raised amount (blue text) with "Raised" label
  • Device count chip (info variant)
• Skeleton loading state shows while data fetches
• Actions are accessible on mobile cards

1.7 Row Actions#

• On a custom (non-General) group:
  • "Edit" → navigates to group detail page
  • "Delete" → opens DeleteDeviceGroupModal
• On the General group:
  • "Edit" → navigates to group detail page (shows read-only view)
  • "Delete" action is NOT available (General cannot be deleted)

1.8 Empty States#

• No groups (except General): Shows empty state with "Create new group" button
• Filters applied, no results: Shows "We couldn't find any groups that match your current filters." with "Clear Filters" button
• Error loading: Shows error state with retry button

1.9 Add Group Button#

• "Add Group" button visible at top of page
• Clicking opens NewDeviceGroupModal

2. Device Group Creation#

2.1 New Device Group Modal#

• Click "Add Group" button — modal opens
• Name field:
  • Required — cannot submit empty
  • Max 40 characters enforced
  • Placeholder: "Enter group name"
• Internal Note field:
  • Optional textarea (3 rows)
  • Placeholder: "Enter internal note"
  • Can be left empty
• No color field in creation modal (set on detail page)
• Create button:
  • Disabled until name is provided
  • Shows loading state during submission
  • Cannot close modal during submission
• On success:
  • Modal closes
  • Device groups list cache invalidated
  • Navigates to new group's detail page
  • New group appears in groups list
• Cancel button closes modal without creating

3. Device Group Detail Page — General Group#

Route: /dashboard/{org}/devices/groups/{generalGroupId}

3.1 Header#

• Group name "General" displays as title
• Lock icon visible next to name
• Breadcrumb links back to "Groups" list
• Footer shows: "${amount} Collected" with group currency

3.2 Read-Only Callout#

• Callout banner displayed at top: "General is your default group. Unassigned devices go here automatically. This group can't be edited or deleted."
• No editable form fields shown
• No color picker shown
• No internal note field shown

3.3 Linked Devices Card#

• Card title shows: "Linked Devices ({count})"
• Displays first 5 devices as clickable links to device detail pages
• Each link shows device name
• If > 5 devices: "See all" link appears → navigates to devices list filtered by this group
• If 0 devices: Empty state message with link to Devices page
• Device links navigate to correct device detail pages

3.4 No Delete Card#

• No "Delete Group" card or button shown for General group

4. Device Group Detail Page — Custom Groups#

Route: /dashboard/{org}/devices/groups/{groupId}

4.1 Header#

• Group name displays as title (no lock icon)
• Breadcrumb links back to "Groups" list
• Footer shows: "${amount} Collected" with group currency

4.2 Main Details Card (Editable)#

• Name field:
  • Shows current group name
  • Change name → Save → Refresh → Name persisted
  • Empty name → validation error (save disabled)
  • Max 40 characters enforced
  • Name updates in header after save
  • Name updates in groups list
• Color field (color picker):
  • Shows current color swatch + hex input
  • Click swatch → color picker opens
  • Pick a color → hex value updates
  • Type valid hex → color swatch updates
  • Change color → Save → Refresh → Color persisted
  • Color required — cannot save without color
  • Invalid hex → validation error shown (FieldError)
  • Color reflects in DeviceGroupChip in devices list (background + text color)
• Internal Note field (textarea):
  • Shows current internal note (or empty)
  • 3 rows visible
  • Enter note → Save → Refresh → Note persisted
  • Clear note → Save → Refresh → Note cleared
  • Optional — can save with empty note

Save Behavior#

• Save button disabled until changes are made
• Save button disabled if validation fails (empty name, missing color)
• Saving shows loading state
• Success toast appears after save
• Error toast appears on failure
• Device groups cache invalidated after save

4.3 Linked Devices Card (Read-Only)#

• Card title shows: "Linked Devices ({count})"
• Displays first 5 devices as clickable links to device detail pages
• Each link shows device name
• If > 5 devices: "See all" link appears → navigates to devices list filtered by this group (/devices?group={groupId})
• If 0 devices: Empty state message with link to Devices page
• Device links navigate to correct device detail pages
• Count matches actual number of devices in this group

4.4 Delete Group Card#

• Description: "Permanently delete this group. All associated devices will be automatically re-assigned to your 'General' group."
• Delete button is red/destructive
• Clicking opens DeleteDeviceGroupModal

5. Device Group Deletion#

5.1 Delete Device Group Modal#

• Shows group name (read-only)
• Destructive warning callout: "Devices assigned to this group will be moved to the General group."
• Delete button is red/destructive
• Shows loading state during deletion
• Cannot close modal during deletion
• On success:
  • Success toast: "Group deleted"
  • Device groups list cache invalidated
  • Navigates back to groups list (or triggers onSuccess callback)
  • Group disappears from list
• Cancel button closes modal without deleting

5.2 Device Reassignment After Deletion#

• Create a custom group with 2-3 devices assigned to it
• Delete the group
• Verify: All devices now show "General" as their group in devices list
• Verify: General group's device count increased by the number of reassigned devices
• Verify: General group's linked devices card shows the reassigned devices
• Verify: Each reassigned device's detail page shows "General" as group

6. Group-Device Relationship#

6.1 Assigning Devices to Groups#

• Go to a device's detail page
• Change the Group dropdown to a custom group → Save
• Verify: Device now appears in the custom group's linked devices
• Verify: Device removed from previous group's linked devices
• Verify: Devices list shows new group chip for this device

6.2 Unassigning Devices (Moving to General)#

• Go to a device's detail page (in a custom group)
• Change the Group dropdown to "General" → Save
• Verify: Device now appears in General group's linked devices
• Verify: Device removed from custom group's linked devices
• Verify: Custom group's device count decremented

6.3 Group Chip Display#

• Device in custom group → DeviceGroupChip shows group name with group color
• Device in General group → DeviceGroupChip shows "General"
• Custom group color change → chip color updates across all views

7. Cross-Cutting Concerns#

7.1 Save Behavior#

• Save button disabled until changes are made
• Save button disabled if validation fails
• Saving shows loading state (spinner/disabled)
• Success toast appears after save
• Error toast appears on failure
• Form data not lost on error

7.2 Loading States#

• Groups list shows loading state while fetching
• Group detail page shows loading state while fetching
• Linked devices card shows loading state

7.3 Error Handling#

• Network error during save → error toast
• Network error during load → error state with retry
• Server validation error → displayed to user

7.4 URL State Persistence#

• Groups list: filters, sort, pagination, search persist in URL params
• Copy/paste URL with params → same view loads
• Browser back/forward navigates between filter states

7.5 Data Consistency#

• Create group → appears in groups list immediately
• Edit group name → list reflects new name
• Edit group color → list and device chips reflect new color
• Delete group → disappears from list, devices reassigned
• Device added to group → linked devices count increments
• Device removed from group → linked devices count decrements

7.6 Mobile Responsiveness#

• List page renders as cards on mobile
• Detail page stacks cards vertically on mobile
• Color picker works on mobile
• Modal displays correctly on mobile

8. End-to-End Flows#

8.1 Create Group and Assign Devices#

1. Click "Add Group" → modal opens
2. Enter group name (e.g., "Lobby Devices")
3. Optionally enter internal note
4. Submit → redirected to new group detail page
5. Set a color (e.g., blue) and save
6. Go to a device's detail page → change group to "Lobby Devices" → save
7. Go back to "Lobby Devices" detail page
8. Verify: Device appears in linked devices card
9. Verify: Device count is 1
10. Go to devices list → verify device shows blue "Lobby Devices" chip

8.2 Delete Group and Verify Reassignment#

1. Ensure a custom group has 3 devices assigned
2. Note the device names
3. Delete the group via detail page or row action
4. Verify: Group no longer in groups list
5. Verify: All 3 devices now show "General" group in devices list
6. Verify: General group linked devices includes the 3 devices
7. Verify: Each device's detail page shows "General" as group

8.3 General Group Immutability#

1. Navigate to General group detail page
2. Verify: Read-only callout is shown
3. Verify: No editable form fields
4. Verify: No delete button
5. Go to groups list → verify no "Delete" action on General row
6. Delete a custom group → verify devices go to General
7. Verify: General group's device count reflects the reassignment

8.4 Color Propagation#

1. Create a group with a distinctive color (e.g., bright red #FF0000)
2. Assign a device to this group
3. Go to devices list → verify DeviceGroupChip shows red color
4. Go back to group detail → change color to green #00FF00 → save
5. Go to devices list → verify DeviceGroupChip now shows green color
6. Verify: Color update propagated without editing the device itself

8.5 Edge Cases#

1. Create a group with the maximum name length (40 chars) → verify it saves and displays correctly (truncated if needed)
2. Create a group with a very long internal note → verify it saves and displays in textarea
3. Delete a group with 0 devices → verify clean deletion (no reassignment needed)
4. Try to navigate to a deleted group's URL → verify appropriate error/redirect
5. Create multiple groups and verify sorting works correctly across all columns

Verification Checklist#