Local Testing Strategies

Local Testing Strategies

This guide provides structured approaches to testing your jsPsych experiment before deployment, helping you catch issues early and ensure your experiment works correctly.

Testing Workflow Overview

A comprehensive testing approach follows these stages:

1. Component Testing: Testing individual experiment components
2. Integration Testing: Testing how components work together
3. End-to-End Testing: Running through the entire experiment
4. Cross-Browser Testing: Verifying compatibility across browsers
5. Performance Testing: Checking timing and resource usage

Setup for Testing

Before starting your testing, ensure your environment is properly configured:

1. Start with a clean development environment:

   yarn dev

2. Open your browser's developer tools (F12 or Cmd+Option+I):

   • Keep the Console tab open to catch errors
   • Use the Network tab to monitor data transfers
   • Use the Performance tab to check timing issues

3. Consider using the following URL parameters for testing:

   • ?debug=true to enable verbose logging
   • ?mock=true to use the mock database

Component Testing

Test individual parts of your experiment in isolation to ensure each functions correctly.

Stimulus Testing

1. Verify that all visual stimuli display correctly:

   • Images load and appear at the expected size
   • Text is readable and properly formatted
   • HTML elements are positioned correctly

2. For audio stimuli:

   • Ensure audio files play correctly
   • Check volume levels are appropriate
   • Verify timing of audio playback

Input Testing

1. Test all response mechanisms:

   • Keyboard inputs register correctly
   • Button clicks and touch interactions work
   • Response timing is recorded accurately

2. Validate input constraints:

   • Required inputs cannot be skipped
   • Invalid inputs are handled gracefully
   • Timeout mechanisms work as expected

Integration Testing

Test how different parts of your experiment work together.

Timeline Flow Testing

1. Test transitions between trials:

   • Trials advance correctly
   • Conditional logic works as expected
   • Randomization produces appropriate variations

2. Check data flow between trials:

   • Data from one trial correctly influences later trials
   • Variables are properly passed through the timeline
   • Cumulative data (like scores) update correctly

Database Integration Testing

1. Test with the mock database:

   • Data is saved correctly after each trial
   • Check the Debug Panel to verify data structure
   • Confirm incremental saves work during the experiment

2. When ready, test with Firestore:

   • Switch to simulateMockDatabase = false
   • Verify authentication works
   • Check data appears in Firestore with correct structure

End-to-End Testing

Perform complete run-throughs of your experiment as if you were a participant.

Complete Experiment Run

1. Start from the welcome page and complete all trials
2. Follow all instructions as a participant would
3. Check the final data summary and completion message

Edge Case Testing

1. Test with unusual inputs:

   • Very fast or very slow responses
   • Skipping trials where allowed
   • Refreshing the page mid-experiment
   • Closing and reopening the browser

2. Test error recovery:

   • What happens if a participant loses internet connection?
   • Does the experiment handle browser back/forward navigation?
   • Test window resize and device orientation changes

Cross-Browser Testing

Ensure your experiment works consistently across different browsers and devices.

Browser Compatibility

Test your experiment in multiple browsers:

1. Google Chrome (primary development browser)
2. Mozilla Firefox
3. Apple Safari
4. Microsoft Edge

Look for any differences in:

• Visual appearance
• Timing and performance
• Keyboard and mouse interactions
• Console errors or warnings

Device Testing

Test on different devices and screen sizes:

1. Desktop computer with large screen
2. Laptop with medium screen
3. Tablet (if targeting tablet users)
4. Mobile phone (if targeting mobile users)

Adjust your experiment design if necessary:

• Use responsive Tailwind CSS classes
• Test different input methods (touch vs. keyboard)
• Ensure text is readable on all screen sizes

Performance Testing

Check that your experiment runs smoothly and efficiently.

Timing Accuracy

For experiments where timing is critical:

1. Use external timing verification when possible (e.g., photodiode for visual stimuli)
2. Test under different system loads
3. Check consistency of inter-trial intervals
4. Verify stimulus duration matches specifications

Resource Usage

Monitor system resources during your experiment:

1. Check memory usage in browser task manager
2. Monitor CPU usage, especially for complex stimuli
3. Watch network activity for data transfers
4. Test on lower-end devices to ensure accessibility

Pre-Deployment Testing Checklist

Before deploying your experiment, complete this final checklist:

Functionality

• All stimuli display correctly
• All response mechanisms work
• Timeline progresses as expected
• Conditional logic works correctly
• Randomization works as designed
• Error handling functions properly

Data Collection

• All required data is collected
• Data format matches expectations
• Incremental data saving works
• Final data summary is accurate
• Firestore connection works correctly
• Participant IDs are correctly recorded

User Experience

• Instructions are clear and accurate
• Loading times are reasonable
• Visual design is consistent
• Text is readable on all screen sizes
• Completion/redirect works correctly
• Overall flow feels smooth and professional

Technical

• No console errors or warnings
• Build completes without errors: yarn build:prod
• Version and git hash are correctly included
• All assets are properly included in the build
• Lint and type checks pass: yarn lint

Automated Testing

While not included in the template by default, consider adding automated testing for complex experiments:

Unit Testing Options

• Jest for JavaScript unit testing
• Testing Library for component testing

Setting Up Basic Jest Tests

1. Install Jest:

   yarn add --dev jest ts-jest @types/jest

2. Create a test configuration in jest.config.js

3. Write simple tests for critical functionality:

   // example-test.js
   describe('Stimulus timing', () => {
     test('stimulus duration is correct', () => {
       // Test code here
     })
   })

4. Add a test script to package.json:

   "scripts": {
     "test": "jest"
   }

Documenting Test Results

Keep track of your testing process:

1. Document any issues found during testing
2. Note browser-specific quirks or workarounds
3. Record performance benchmarks for different devices
4. Update your testing plan based on findings

This documentation will be valuable for future updates and for understanding participant experiences.