Skip to content

MOBILE_TESTING.md

Latest commit

 

History

History
180 lines (132 loc) · 4.87 KB

MOBILE_TESTING.md

File metadata and controls

180 lines (132 loc) · 4.87 KB

Mobile Testing Guide

This document describes how to run and debug mobile UI tests for MQTT Explorer.

Overview

The mobile tests simulate MQTT Explorer running in a mobile browser (Google Pixel 6 viewport: 412x914px) and generate demo videos showing the mobile user experience.

Prerequisites

System Dependencies

sudo apt-get install -y ffmpeg tmux xvfb x11vnc mosquitto

Node Dependencies

yarn install
npx playwright install --with-deps chromium

Running Mobile Tests

1. Build the Application

yarn build:server  # For browser mode

2. Run Tests

./scripts/uiTestsMobile.sh

This will:

  • Start Xvfb (virtual framebuffer)
  • Start mosquitto MQTT broker
  • Start MQTT Explorer server in browser mode
  • Run Playwright tests with mobile viewport
  • Record video of the test session

3. Post-Process Video

./scripts/prepareVideoMobile.sh

This converts the raw video to MP4 and GIF formats and creates individual segments for each test scene.

Output Files

  • ui-test-mobile.mp4 - Full mobile test video (MP4)
  • ui-test-mobile.gif - Full mobile test video (GIF)
  • segment-mobile-*.gif - Individual scene segments
  • scenes-mobile.json - Scene timing metadata

All video files are automatically excluded from git (see .gitignore).

Debugging

View Test in VNC

During test execution, you can connect with VNC to watch in real-time:

# Password: bierbier
vncviewer localhost:5900

Common Issues

1. Playwright Browsers Not Installed

Error: Executable doesn't exist at .../chromium_headless_shell-1200/chrome-headless-shell

Solution:

npx playwright install --with-deps chromium

2. Video Encoding Fails

Error: height not divisible by 2

Solution: Ensure viewport height is even. Mobile viewport is set to 412x914 (not 915).

3. Elements Outside Viewport

Error: element is outside of the viewport

Solution: The fix adds scrollIntoViewIfNeeded() before clicking elements. For modal/dialog elements that intercept clicks, use force: true.

4. MQTT Broker Already Running

Error: Address already in use on port 1883

Solution: Kill existing mosquitto process:

pkill mosquitto

Mobile UI Enhancements

The tests revealed several mobile UI improvements that were implemented:

1. Connection Dialog Responsiveness

Added responsive CSS to ConnectionSetup.tsx:

  • Mobile viewports use 95vw width and 85vh height
  • Enabled scrolling on the right panel
  • Hide profile list on mobile to save space

2. Click Handling

Enhanced clickOn helper in util/index.ts:

  • Added scrollIntoViewIfNeeded() to ensure elements are in viewport
  • Support for force: true to bypass overlay elements

3. Tree Node Expansion

Updated expandTopic helper:

  • Use force: true for tree clicks to bypass accordion overlays
  • Better handling of nested topic expansion

Test Scenes

The mobile demo includes these scenes:

  1. mobile_intro - Introduction screen
  2. mobile_connect - Connect to MQTT broker
  3. mobile_browse_topics - Browse topic tree
  4. mobile_search - Search and filter topics
  5. mobile_view_message - View message details
  6. mobile_json_view - JSON formatting display
  7. mobile_clipboard - Copy operations
  8. mobile_plots - Numeric data visualization
  9. mobile_menu - Settings and menu
  10. mobile_end - Conclusion screen

CI Integration

Mobile tests run in the demo-video-mobile job in .github/workflows/tests.yml:

demo-video-mobile:
  runs-on: ubuntu-latest
  container:
    image: ghcr.io/thomasnordquist/mqtt-explorer-ui-tests:latest
  steps:
    - name: Generate Mobile Demo Video
      run: ./scripts/uiTestsMobile.sh
    - name: Post-processing
      run: ./scripts/prepareVideoMobile.sh

Videos are uploaded to S3 and linked in PR comments.

Technical Notes

Viewport Configuration

  • Width: 412px (Pixel 6)
  • Height: 914px (must be even for h264 encoding)
  • Device Scale Factor: 2.625
  • Mobile Mode: Enabled with touch events

Video Recording

  • Raw video: YUV420P format
  • Frame rate: 20 fps
  • Recording tool: ffmpeg via tmux

Post-Processing

  • MP4 encoding: h264 codec
  • GIF palette: 256 colors optimized per segment
  • Segment creation: Based on scene timing in scenes-mobile.json

Future Improvements

Potential areas for enhancement:

  1. Touch Gestures - Add swipe and pinch interactions
  2. Performance - Optimize for slower mobile networks
  3. Accessibility - Larger touch targets, better contrast
  4. PWA Support - Add manifest for "add to home screen"
  5. Orientation - Test landscape mode

References