Skip to content

Phase 2 Manual Testing Guide - Positron

Complete step-by-step instructions for verifying unified state functionality in Positron IDE.

Setup

Before starting tests: 1. Build the extension: npm run compile 2. Open Positron 3. Open this project folder in Positron 4. Press F5 to launch Extension Development Host 5. Open the test data folder: tests/data/

Test Data Files

  • yeast_trna_reads.pod5 - 180 reads POD5 file
  • yeast_trna_mappings.bam - Corresponding BAM file (alignments)

Test 1: File Panel Load → Samples Panel Aware

Objective: Verify that loading a POD5 via File Panel notifies Samples Panel through unified state

Steps

  1. Open the File Panel
  2. View → Sidebar → Look for "Squiggy File Explorer" panel

  3. Should be empty initially

  4. Open POD5 File

  5. Command Palette (Cmd+Shift+P)
  6. Type: Squiggy: Open POD5 File
  7. Select: tests/data/yeast_trna_reads.pod5

  8. Click "Open"

  9. Verify File Panel Updated

  10. ✅ File Panel should show:

    • Filename: yeast_trna_reads.pod5
    • Type: POD5
    • Number of reads: 180
    • File size: Should display (e.g., "1.2 MB")

  11. Check Extension Output

  12. View → Output Panel
  13. Select "Extension Host" from dropdown

  14. Look for logs:

    • [FilePanelProvider] Unified state changed, now showing 1 items
    • [SamplesPanelProvider] messages if Samples Panel is subscribed

  15. Expected Result ✅

  16. File Panel displays the loaded POD5
  17. No errors in console
  18. Extension state contains the loaded item

Test 2: Samples Panel Load → File Panel Aware

Objective: Verify that loading a sample via Samples Panel notifies File Panel through unified state

Steps

  1. Open Samples Panel
  2. View → Sidebar → Look for "Sample Comparison Manager"

  3. Should be empty initially

  4. Load Sample via Demo

  5. Click "Load Demo Session" button in Samples Panel (if available)

  6. OR manually load: Command Palette → Squiggy: Load Samples From Dropped

  7. Verify Samples Panel Updated

  8. ✅ Samples Panel should show:

    • At least one sample entry
    • Sample name displayed
    • Read count
    • File size

  9. Check File Panel

  10. File Panel should now show:

    • The sample's POD5 file
    • Type: Should indicate it's from a sample
    • Same read count as Samples Panel shows

  11. Check Console Logs

  12. Look for:

    • [FilePanelProvider] Unified state changed, now showing X items
    • [SamplesPanelProvider] onLoadedItemsChanged messages

  13. Expected Result ✅

  14. Both panels show consistent data
  15. File Panel automatically updated when Samples Panel loaded data
  16. No console errors

Test 3: BAM Association Updates Both Panels

Objective: Verify that associating a BAM file updates both File and Samples panels

Prerequisites

  • Complete Test 1 (POD5 loaded)
  • Have BAM file available: tests/data/yeast_trna_mappings.bam

Steps

  1. Verify Current State
  2. File Panel shows POD5 without BAM info

  3. Check console: No BAM association yet

  4. Load BAM File

  5. Command Palette → Squiggy: Open BAM File
  6. Select: tests/data/yeast_trna_mappings.bam

  7. Click "Open"

  8. Verify File Panel Updated

  9. ✅ File Panel should show:

    • POD5 still displayed
    • New field showing: "Alignments: Yes" or similar
    • BAM path associated with POD5

  10. Verify Samples Panel Updated (if samples loaded)

  11. If samples are loaded:

    • Each sample should show: "Has BAM: Yes"
    • Alignment info displayed

  12. Check Console

  13. Look for:

    • [FilePanelProvider] Unified state changed (BAM update)
    • [SamplesPanelProvider] Unified state changed (if samples loaded)

  14. Expected Result ✅

  15. Both panels show BAM association
  16. Events fired for state update
  17. No console errors

Test 4: Comparison Mode Selection

Objective: Verify comparison mode selection through unified state

Prerequisites

  • Multiple samples loaded in Samples Panel (load demo session or multiple samples)

Steps

  1. Open Samples Panel

  2. Verify at least 2 samples are displayed

  3. Select Samples for Comparison

  4. Click checkbox next to first sample
  5. Click checkbox next to second sample

  6. ✅ Both should show as selected (checkmarks visible)

  7. Check Console Logs

  8. Look for:

    • [SamplesPanelProvider] Comparison selection changed: [sample:name1, sample:name2]
    • Or similar indicating comparison items set

  9. Verify Unified State

  10. Command Palette → Squiggy: Debug Extension State (if command exists)

  11. Or check Output panel for state information

  12. Trigger Comparison

  13. Click "Compare Samples" button in Samples Panel

  14. Should generate plot with 2+ samples overlaid

  15. Expected Result ✅

  16. Samples appear selected
  17. Console shows comparison IDs with "sample:" prefix
  18. Plot generates with correct samples
  19. No errors

Test 5: Item Removal Synchronization

Objective: Verify that removing items from one panel updates other panels

Steps

  1. Verify Starting State
  2. File Panel shows 1+ items

  3. Samples Panel shows 1+ samples

  4. Unload POD5 from File Panel

  5. Command Palette → Squiggy: Close POD5 File

  6. Click "Confirm" in dialog

  7. Verify File Panel Updated

  8. ✅ File Panel should become empty or show remaining items

  9. Check Samples Panel (if samples were from this POD5)

  10. If samples depend on this POD5:

    • Samples Panel might also update
    • Or samples remain if they're independent

  11. Check Console

  12. Look for:

    • [FilePanelProvider] Unified state changed, now showing 0 items
    • [SamplesPanelProvider] updates if affected

  13. Expected Result ✅

  14. File Panel clears correctly
  15. Other panels update if dependent
  16. State remains consistent
  17. No orphaned references

Test 6: Session Save/Restore

Objective: Verify that sessions properly persist and restore unified state

Prerequisites

  • At least 1 POD5 loaded
  • Ideally: 1-2 samples with BAM association

Steps

  1. Verify Current State
  2. Note what's loaded in File Panel
  3. Note what's loaded in Samples Panel

  4. Note any comparison selections

  5. Save Session

  6. File → Save Workspace (or similar)

  7. Or use extension command: Squiggy: Save Session

  8. Check Session File

  9. Look in workspace settings or .vscode/settings.json

  10. Session should contain sample data and paths

  11. Close All Files

  12. Command Palette → Squiggy: Close POD5 File
  13. Command Palette → Squiggy: Close BAM File

  14. Verify panels are empty

  15. Reload Session

  16. Reload the Positron window (Cmd+R or View → Reload)

  17. Wait for extension to activate

  18. Verify Restoration

  19. ✅ File Panel should show:

    • Same files as before reload
    • Same metadata (read counts, sizes)

  20. ✅ Samples Panel should show:

    • Same samples as before
    • BAM associations if they existed

  21. ✅ Check Console:

    • Look for session restore messages
    • No errors during restoration

  22. Expected Result ✅

  23. All items restored exactly as they were
  24. Session state fully recovered
  25. Comparison selections restored (if applicable)
  26. No console errors

Test 7: Edge Case - Duplicate Item

Objective: Verify that adding the same file twice replaces rather than duplicates

Steps

  1. Load POD5
  2. Command Palette → Squiggy: Open POD5 File

  3. Select same file twice (or load, then load again)

  4. Check File Panel

  5. ✅ Should show exactly 1 POD5 entry (not 2)

  6. File info updated (if metadata changed)

  7. Check Console

  8. Should see state update, not duplicate addition

  9. Expected Result ✅

  10. No duplicate items in unified state
  11. Previous item replaced with new one
  12. Consistent behavior

Test 8: Edge Case - Removal During Comparison

Objective: Verify that removing a sample in comparison mode cleans up automatically

Prerequisites

  • Multiple samples loaded
  • At least 2 samples selected for comparison

Steps

  1. Verify Comparison Mode
  2. Samples Panel shows selected checkmarks

  3. Console shows comparison IDs

  4. Unload Sample from Comparison

  5. Right-click sample → "Unload Sample"

  6. Click "Yes" to confirm

  7. Check Console

  8. Look for:

    • [SamplesPanelProvider] Comparison selection changed
    • Updated comparison IDs should not include removed sample

  9. Verify File Panel

  10. File Panel should no longer show that sample's POD5

  11. Expected Result ✅

  12. Sample removed from file panel
  13. Sample removed from comparison selections
  14. Events fired correctly
  15. No orphaned state

Test 9: Large File List Performance

Objective: Verify UI remains responsive with many items

Steps

  1. Load Multiple Samples
  2. Use Command Palette to load 10-20 samples

  3. Or load demo session that has many samples

  4. Monitor Performance

  5. File Panel should render all items
  6. UI should remain responsive (no freezing)

  7. Scrolling should be smooth

  8. Check Console

  9. Look for performance warnings

  10. Event firing should be reasonable frequency

  11. Trigger Updates

  12. Load/unload additional files

  13. Verify UI updates quickly

  14. Expected Result ✅

  15. UI responsive with 50+ items
  16. No performance degradation
  17. Events fire efficiently

Test 10: Regression - Legacy Workflow

Objective: Verify backward compatibility with legacy (non-unified) code paths

Steps

  1. Single File Mode
  2. Load POD5 via command
  3. Load BAM via command

  4. Verify plots generate correctly with old API

  5. Plot Generation

  6. Select read from reads panel
  7. Plot should generate as before

  8. No errors

  9. File Operations

  10. Open/close files via commands

  11. Should work exactly as before unified state

  12. Expected Result ✅

  13. All legacy features work unchanged
  14. No regressions in existing functionality

Verification Checklist

After running all tests, verify:

  • [ ] All console logs are clean (no errors)
  • [ ] File Panel always matches Samples Panel on shared files
  • [ ] Session save/restore works end-to-end
  • [ ] Comparison mode selections properly maintained
  • [ ] Removal of items properly synchronized
  • [ ] BAM association updates both panels
  • [ ] No duplicate items in unified state
  • [ ] UI responsive with 50+ items
  • [ ] Legacy workflows still function
  • [ ] No memory leaks (check Chrome DevTools)

Troubleshooting

"File Panel shows file but Samples Panel doesn't know about it"

  • Check Extension Host output for errors
  • Look for _handleLoadedItemsChanged in logs
  • Verify subscription is active in Samples Panel constructor

"BAM association not showing in both panels"

  • Verify BAM file path is correct
  • Check console for BAM loading errors
  • Verify addLoadedItem is called with updated item

"Session doesn't restore"

  • Check that items were in unified state before save
  • Verify toSessionState() is populating samples correctly
  • Check Extension Host logs for restoration errors

"Removed item still appears in panels"

  • Verify removeLoadedItem is being called
  • Check that item ID is exactly correct (prefixes matter)
  • Look for lingering event subscriptions

Notes

  • Console output is verbose - this is helpful for debugging
  • Event handlers may fire multiple times during operations (expected)
  • Session restore may take a few seconds
  • BAM loading requires the file to exist on disk
  • Demo session loads test data from tests/data/

Good luck with testing! 🚀