NizamInternal

Devices

Comprehensive manual QA testing plan for devices — physical kiosk/terminal units (~170 tests).

Context#

Comprehensive manual QA testing plan for devices — the physical kiosk/terminal units (StandPro and Handheld) that accept donations. Devices are assigned to a Device Group (for organization) and a Device Template (for configuration). This plan covers the devices list page, device registration, individual device management, and the delete/retire lifecycle.

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 1 published campaign, 1 device group (General exists by default), and 1 device template must exist

1. Devices Section Layout#

Route: /dashboard/{org}/devices

1.1 Tab Navigation#

  • Three tabs visible at the top: Devices (default), Groups, Templates
  • Clicking each tab navigates to the correct route:
    • Devices → /dashboard/{org}/devices
    • Groups → /dashboard/{org}/devices/groups
    • Templates → /dashboard/{org}/devices/templates
  • Active tab is visually highlighted
  • Tab navigation preserves no cross-tab state (each tab has its own filters/sort)

1.2 Pre-fetching#

  • Navigating to the Devices section pre-loads campaigns and campaign groups data
  • Templates tab loads instantly (content options already available from pre-fetch)

2. Devices List Page#

Route: /dashboard/{org}/devices

2.1 Data Table Display#

  • Page loads and displays all devices in a table
  • Default visible columns:
    • Device Name — sortable, truncated with tooltip for long names
    • Status — DeviceStatusChip (Online = green, Offline = yellow, Retired = grey)
    • Group — DeviceGroupChip with custom color from group
    • Template — DeviceTemplateChip with icon
    • Raised — currency-formatted amount, right-aligned
    • Type — DeviceTypeChip (StandPro or Handheld) with icon
    • Created — formatted date
  • All column data matches expected values for each device
  • Currency formatting is correct (e.g., $1,234.56)
  • Dates are formatted correctly

2.2 Optional Columns#

  • Click column settings and toggle on each optional column:
    • ID
    • Terminal ID
    • Group ID
    • Template ID
    • Monitoring (shows "Enabled" or "Off")
  • Each column shows correct data
  • Column preferences persist after page refresh (stored in localStorage)

2.3 Sorting#

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

2.4 Filtering#

  • Status (toggle group, multi-select):
    • Online — filters to online devices only
    • Offline — filters to offline devices only
    • Retired — filters to retired devices only
    • Combining Online + Offline — shows both, excludes Retired
  • Type (toggle group, multi-select):
    • StandPro — filters to StandPro devices
    • Handheld — filters to Handheld devices
    • Combining both — shows all (no filter effect)
  • Amount Raised (range filter):
    • Set min amount — filters correctly
    • Set max amount — filters correctly
    • Set both min and max — range filter works
  • Combining multiple filters works correctly (e.g., Online + StandPro + Raised > $100)
  • Clearing filters restores full list
  • Filter state persists in URL params

2.5 Search#

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

2.6 Pagination#

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

2.7 Mobile Responsive#

  • Resize to mobile width — table switches to card view
  • Mobile card shows:
    • Device name
    • Status chip (Online/Offline/Retired)
    • Raised amount
    • Type chip (StandPro/Handheld)
    • Group chip with color
    • Template chip with icon
  • Actions are accessible on mobile cards

2.8 Row Actions#

  • On an Online/Offline device:
    • "Edit" → navigates to device detail page
    • "Delete" or "Retire" → opens DeleteDeviceModal
      • If raised = 0 → shows "Delete Device" mode
      • If raised > 0 → shows "Retire Device" mode
  • On a Retired device:
    • "Edit" → navigates to device detail page
    • No delete/retire action (already retired)

2.9 Empty States#

  • No devices at all: Shows empty state with message "Once your devices are provisioned, you'll be able to manage them here."
  • Filters applied, no results: Shows "We couldn't find any devices that match your current filters." with "Clear Filters" button
  • Error loading: Shows error state with retry button

3. Device Registration#

3.1 Registration Page#

Route: /register/device?token={token}

  • Page loads with valid registration token
  • Single organization: Auto-redirects to /dashboard/{slug}/devices?token={token}
  • Multiple organizations: Shows organization selection UI
    • Displays organization logos and names
    • Clicking an organization redirects to its dashboard with token
  • Missing token → appropriate error/redirect

3.2 Register Device Modal#

Triggered: When devices list page has ?token= query parameter

  • Modal opens automatically when token is in URL
  • Device Name field:
    • Required — cannot submit empty
    • Max 40 characters enforced
    • Placeholder: "Enter device name"
  • Group dropdown:
    • Shows all available device groups
    • Auto-selects if only 1 group exists
    • Hidden if locked to one group (org has only General)
  • Template dropdown:
    • Shows all available device templates
    • Auto-selects if only 1 template exists

Inline Template Creation (when no templates exist)#

  • When organization has 0 templates, inline creation fields appear:
    • Template Name (required, max 40 chars)
    • Content (required combobox — campaigns + campaign groups)
      • Campaign Groups shown first with header
      • Campaigns shown below with header
      • Only PUBLISHED campaigns/groups available
    • Checkout Mode (required dropdown: Express, Quick, Standard)
  • Inline template is created first, then device uses it

Submit Behavior#

  • Create button disabled until all required fields filled
  • Submitting creates the device
  • Redirects to newly created device's detail page
  • Device appears in devices list
  • Device list cache invalidated
  • Template list cache invalidated (if inline template was created)
  • Token is consumed (cannot re-use)
  • Cancel closes modal without creating

4. Device Detail Page#

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

4.1 Header#

  • Device name displays as title
  • Status chip shows next to name (Online/Offline/Retired)
  • Breadcrumb links back to Devices list
  • Footer shows: "${amount} Collected" with device currency

4.2 Main Details Card (Editable)#

  • Device Name field:
    • Shows current name
    • Change name → Save → Refresh → Name persisted
    • Name updates in header after save
    • Empty name → validation error (save disabled)
    • Max 40 characters enforced
  • Group dropdown:
    • Shows all available device groups
    • Current group is pre-selected
    • Change group → Save → Refresh → Group persisted
    • Group chip updates in devices list
    • Group required — cannot save without selection
  • Template dropdown:
    • Shows all available device templates
    • Current template is pre-selected
    • Change template → Save → Refresh → Template persisted
    • Template chip updates in devices list
    • Template required — cannot save without selection
  • Enable Monitoring toggle:
    • Label: "Is this device expected to be on 24/7"
    • ON → Save → Refresh → persisted
    • OFF → Save → Refresh → persisted
    • Monitoring column in list updates (if visible)

Save Behavior#

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

4.3 Device Info Card (Read-Only)#

  • Type field: Shows DeviceTypeChip (StandPro or Handheld)
  • Terminal ID field: Shows terminal ID or "-" if null
  • Both fields are read-only (no edit capability)

4.4 Delete/Retire Device Card#

When raised = 0 (Delete Mode)#

  • Shows "Delete Device" button (destructive/red)
  • Clicking opens DeleteDeviceModal in "delete" mode
  • Modal title: "Delete Device"
  • Modal message: "Are you sure you want to delete this device? This action cannot be undone."
  • Warning callout: "This device will need to be set up again if you want to use it in the future."
  • Shows device name
  • Confirming deletes the device permanently
  • Navigates back to devices list
  • Device disappears from list
  • Device count decrements on associated group and template

When raised > 0 (Retire Mode)#

  • Shows "Retire Device" button (destructive/red)
  • Clicking opens DeleteDeviceModal in "retire" mode
  • Modal title: "Retire Device"
  • Modal message: "Are you sure you want to retire this device?"
  • Warning callout: "All donation data associated with this device will be preserved."
  • Shows device name
  • Confirming retires the device (status becomes RETIRED)
  • Navigates back to devices list
  • Device shows Retired status chip in list
  • Donation data preserved (raised amount still shown)

5. Device Status Lifecycle#

5.1 Status Transitions#

  • New device starts as ONLINE or OFFLINE (based on physical state)
  • Physical device goes offline → status automatically updates to OFFLINE
  • Physical device comes back online → status automatically updates to ONLINE
  • Admin retires device → status becomes RETIRED
  • Admin deletes device (raised = 0) → device removed entirely

5.2 Status Display#

  • Online: Green chip, all actions available
  • Offline: Yellow/warning chip, all actions available
  • Retired: Grey/muted chip, limited actions (edit only, no delete/retire)

5.3 Retired Device Behavior#

  • Retired devices still appear in devices list
  • Retired device detail page is accessible (read-only or limited edit)
  • Retired device's donation data is preserved
  • Retired device no longer appears in group/template "linked devices" counts (verify)

6. Chip Components#

6.1 DeviceStatusChip#

  • Online → success variant (green background, green text)
  • Offline → warning variant (yellow background, yellow text)
  • Retired → muted variant (grey background, grey text)

6.2 DeviceTypeChip#

  • StandPro → shows StandPro icon + "StandPro" label
  • Handheld → shows Handheld icon + "Handheld" label
  • Icon color: primary-500

6.3 DeviceGroupChip#

  • Shows group name text
  • Background: group color at 20% opacity
  • Text: darkened version of group color
  • Shows "-" if group not found (edge case)

6.4 DeviceTemplateChip#

  • Shows template name text with template icon
  • Icon: primary-500 color
  • Shows "-" if template not found (edge case)

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
  • Data not lost on error (form retains values)

7.2 Loading States#

  • Devices list shows loading state while fetching
  • Device detail page shows loading state while fetching
  • Dropdowns in detail page load group/template options

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#

  • Devices 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#

  • Edit device name → devices list reflects new name
  • Change device group → devices list group chip updates
  • Change device template → devices list template chip updates
  • Delete/retire device → devices list updates
  • Group/template device counts update after device changes

7.6 Mobile Responsiveness#

  • List page renders as cards on mobile
  • Detail page stacks cards vertically on mobile
  • Registration modal displays correctly on mobile
  • Dropdowns and selects work on mobile

8. End-to-End Flows#

8.1 Full Device Registration Flow#

  1. Generate a device registration token (physical device setup)
  2. Navigate to registration URL with token
  3. If multiple orgs: select the correct organization
  4. Register device modal opens on the devices list page
  5. Enter device name
  6. Select a group (or accept auto-selected)
  7. Select a template (or create inline if none exist)
  8. Submit registration
  9. Verify: Redirected to new device detail page
  10. Verify: Device name, group, template all correct
  11. Verify: Device appears in devices list
  12. Verify: Device appears in selected group's linked devices
  13. Verify: Device appears in selected template's linked devices
  14. Verify: Token is consumed (re-visiting URL doesn't re-open modal)

8.2 Device Reassignment Flow#

  1. Open an existing device's detail page
  2. Change the group to a different group
  3. Save → verify success
  4. Go to old group's detail page → device no longer in linked devices
  5. Go to new group's detail page → device now in linked devices
  6. Change the template to a different template
  7. Save → verify success
  8. Go to old template's detail page → device no longer in linked devices
  9. Go to new template's detail page → device now in linked devices

8.3 Device Retirement Flow#

  1. Find a device with raised > 0
  2. Open its detail page
  3. Click "Retire Device" → confirm in modal
  4. Verify: Redirected to devices list
  5. Verify: Device status is now "Retired" (grey chip)
  6. Verify: Donation data preserved (raised amount still shows)
  7. Verify: Device detail page still accessible
  8. Verify: No delete/retire action on retired device's row in list

8.4 Device Deletion Flow#

  1. Find a device with raised = 0 (or create a new one)
  2. Open its detail page
  3. Click "Delete Device" → confirm in modal
  4. Verify: Redirected to devices list
  5. Verify: Device no longer in list
  6. Verify: Device no longer in group's linked devices
  7. Verify: Device no longer in template's linked devices

8.5 Inline Template Creation During Registration#

  1. Ensure organization has 0 device templates
  2. Start device registration with token
  3. Modal shows inline template creation fields
  4. Enter template name, select content (published campaign), select checkout mode
  5. Enter device name and select group
  6. Submit registration
  7. Verify: Template was created (appears in Templates tab)
  8. Verify: Device was created with the new template assigned
  9. Verify: Template detail page shows this device in linked devices

Verification Checklist#

AreaTotal TestsPassFailNotes
Section Layout~5
Devices List Page~40
Device Registration~25
Device Detail Page~30
Status Lifecycle~10
Chip Components~12
Cross-Cutting~15
E2E Flows~30
TOTAL~170