TenantAtlas/specs/185-settings-catalog-readable/MANUAL_VERIFICATION_GUIDE.md

Feature 185: Manual Verification Guide (Phase 6)

Quick Start

Estimated Time: 20 minutes
Prerequisites: Settings Catalog policy exists in database with snapshot

---

Verification Steps

Step 1: Navigate to Policy View (2 min)

1. Open browser: http://localhost (or your Sail URL)
2. Login to Filament admin panel
3. Navigate to Policies resource
4. Click on a Settings Catalog policy (look for settingsCatalogPolicy type)

Expected Result:

• ✅ Page loads without errors
• ✅ Policy details visible
• ✅ No browser console errors

If it fails:

• Check browser console for JavaScript errors
• Run ./vendor/bin/sail artisan optimize:clear
• Verify policy has versions relationship loaded

---

Step 2: Verify Tabs Present (2 min)

Action: Look at the Policy View infolist

Expected Result:

• ✅ "Settings" tab visible
• ✅ "JSON" tab visible
• ✅ Settings tab is default (active)

If tabs missing:

• Check if policy is actually Settings Catalog type
• Verify PolicyResource.php has Tabs component for policy_content
• Check Feature 002 JSON viewer implementation

---

Step 3: Verify Settings Tab - Accordion (5 min)

Action: Click on "Settings" tab (if not already active)

Expected Result:

• ✅ Accordion groups render
• ✅ Each group has:
  • Title (e.g., "Device Vendor Msft", "Biometric Authentication")
  • Description (if available)
  • Setting count badge (e.g., "12 settings")
• ✅ First group expanded by default
• ✅ Other groups collapsed
• ✅ Click group header toggles collapse/expand

If accordion missing:

• Check if metadata.definitions_cached === true in snapshot
• Verify normalizer returns groups structure
• Check Blade component exists: settings-catalog-grouped.blade.php

---

Step 4: Verify Display Names (Not Definition IDs) (3 min)

Action: Expand a group and look at setting labels

Expected Result:

• ✅ Labels show human-readable names:
  • ✅ "Biometric Authentication" (NOT device_vendor_msft_policy_biometric_authentication)
  • ✅ "Password Minimum Length" (NOT device_vendor_msft_policy_password_minlength)
• ✅ No device_vendor_msft_... visible in labels

If definition IDs visible:

• Check if definitions cached in database: SettingsCatalogDefinition::count()
• Run policy sync manually to trigger cache warming
• Verify fallback message visible: "Definitions not yet cached..."

---

Step 5: Verify Value Formatting (5 min)

Action: Look at setting values in different groups

Expected Result:

• ✅ Boolean values: Badges with "Enabled" (green) or "Disabled" (gray)
• ✅ Integer values: Formatted with separators (e.g., "1,000" not "1000")
• ✅ String values: Truncated if >100 chars with "..."
• ✅ Choice values: Show choice label (not raw ID)

If formatting incorrect:

• Check formatSettingsCatalogValue() method in PolicyNormalizer
• Verify Blade component conditionals for value types
• Inspect browser to see actual rendered HTML

---

Step 6: Test Copy Buttons (2 min)

Action: Find a setting with a long value, click copy button

Expected Result:

• ✅ Copy button visible for long values
• ✅ Click copy button → clipboard receives value
• ✅ Button shows checkmark for 2 seconds
• ✅ Button returns to copy icon after timeout

If copy button missing/broken:

• Check Alpine.js loaded (inspect page source for @livewireScripts)
• Verify clipboard API available (requires HTTPS or localhost)
• Check browser console for JavaScript errors

---

Step 7: Test Search Filtering (Optional - if search visible) (2 min)

Action: Type in search box (if visible at top of Settings tab)

Expected Result:

• ✅ Search box visible with placeholder "Search settings..."
• ✅ Type search query (e.g., "biometric")
• ✅ Only matching settings shown
• ✅ Non-matching groups hidden/empty
• ✅ Clear search resets view

If search not visible:

• This is expected for MVP (Blade-level implementation, no dedicated input yet)
• Search logic exists in Blade template but may need Livewire wiring

---

Step 8: Verify JSON Tab (2 min)

Action: Click "JSON" tab

Expected Result:

• ✅ Tab switches to JSON view
• ✅ Snapshot renders with syntax highlighting
• ✅ Copy button visible at top
• ✅ Click copy button → full JSON copied to clipboard
• ✅ Can switch back to Settings tab

If JSON tab broken:

• Verify Feature 002 implementation still intact
• Check pepperfm/filament-json package installed
• Verify PolicyResource.php has JSON ViewEntry

---

Step 9: Test Fallback Message (3 min)

Action: Find a Settings Catalog policy WITHOUT cached definitions (or manually delete definitions from database)

Steps to test:

1. Run: ./vendor/bin/sail artisan tinker
2. Execute: \App\Models\SettingsCatalogDefinition::truncate();
3. Navigate to Policy View for Settings Catalog policy
4. Click Settings tab

Expected Result:

• ✅ Settings tab shows fallback message:
  • "Definitions not yet cached. Settings will be shown with raw IDs."
  • Helper text: "Switch to JSON tab or wait for next sync"
• ✅ JSON tab still accessible
• ✅ No error messages or broken layout

If fallback not visible:

• Check conditional rendering in PolicyResource.php
• Verify metadata.definitions_cached correctly set in snapshot
• Check Blade component has fallback TextEntry

---

Step 10: Test Dark Mode (Optional) (2 min)

Action: Toggle Filament dark mode (if available)

Expected Result:

• ✅ Accordion groups adjust colors
• ✅ Badges adjust colors (dark mode variants)
• ✅ Text remains readable
• ✅ No layout shifts or broken styles

If dark mode broken:

• Check Blade component uses dark: Tailwind classes
• Verify Filament Section components support dark mode
• Inspect browser to see actual computed styles

---

Success Criteria Checklist

After completing all steps, mark these off:

• T023: JSON tab works (from Feature 002)
• T024: Fallback message shows when definitions not cached
• T025: JSON viewer only renders on Policy View (not globally)

---

Common Issues & Solutions

Issue: "Definitions not yet cached" persists

Cause: SyncPoliciesJob hasn't run yet or Graph API call failed

Solution:

1. Manually trigger sync:

   ./vendor/bin/sail artisan tinker
   

   $policy = \App\Models\Policy::first();
   \App\Jobs\SyncPoliciesJob::dispatch();
   

2. Check logs for Graph API errors:

   ./vendor/bin/sail artisan log:show
   

Issue: Accordion doesn't render

Cause: Blade component error or missing groups

Solution:

1. Check browser console for errors
2. Verify normalizer output:

   ./vendor/bin/sail artisan tinker
   

   $policy = \App\Models\Policy::first();
   $snapshot = $policy->versions()->orderByDesc('captured_at')->value('snapshot');
   $normalizer = app(\App\Services\Intune\PolicyNormalizer::class);
   $groups = $normalizer->normalizeSettingsCatalogGrouped($snapshot['settings'] ?? []);
   dd($groups);
   

Issue: Copy buttons don't work

Cause: Alpine.js not loaded or clipboard API unavailable

Solution:

1. Verify Alpine.js loaded:
   • Open browser console
   • Type window.Alpine → should return object
2. Check HTTPS or localhost (clipboard API requires secure context)
3. Fallback: Use "View JSON" tab and copy from there

---

Next Steps After Verification

If All Tests Pass ✅

Proceed to Phase 7: Testing & Validation

1. Write unit tests (T026-T031)
2. Write feature tests (T032-T037)
3. Run Pest suite (T038-T039)
4. Manual QA walkthrough (T040-T042)

Estimated Time: ~5-7 hours

If Issues Found ⚠️

1. Document issues in specs/185-settings-catalog-readable/ISSUES.md
2. Fix critical issues (broken UI, errors)
3. Re-run verification steps
4. Proceed to Phase 7 only after verification passes

---

Reporting Results

After completing verification, update tasks.md:

# Mark T023-T025 as complete
vim specs/185-settings-catalog-readable/tasks.md

Add implementation notes:

- [X] **T023** Verify JSON tab still works
  - **Implementation Note**: Verified tabs functional, JSON viewer renders snapshot

- [X] **T024** Add fallback for policies without cached definitions
  - **Implementation Note**: Fallback message shows info with guidance to JSON tab

- [X] **T025** Ensure JSON viewer only renders on Policy View
  - **Implementation Note**: Verified scoping correct, only shows on Policy resource

---

Contact & Support

If verification fails or you need assistance:

1. Check logs: ./vendor/bin/sail artisan log:show
2. Review implementation status: specs/185-settings-catalog-readable/IMPLEMENTATION_STATUS.md
3. Review code: app/Services/Intune/, app/Filament/Resources/PolicyResource.php
4. Ask for help with specific error messages and context

---

End of Manual Verification Guide