4de52aba7c
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: thomasnordquist <7721625+thomasnordquist@users.noreply.github.com> Co-authored-by: Thomas Nordquist <thomasnordquist@users.noreply.github.com>
181 lines
4.9 KiB
Markdown
181 lines
4.9 KiB
Markdown
# 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
|
|
```bash
|
|
sudo apt-get install -y ffmpeg tmux xvfb x11vnc mosquitto
|
|
```
|
|
|
|
### Node Dependencies
|
|
```bash
|
|
yarn install
|
|
npx playwright install --with-deps chromium
|
|
```
|
|
|
|
## Running Mobile Tests
|
|
|
|
### 1. Build the Application
|
|
```bash
|
|
yarn build:server # For browser mode
|
|
```
|
|
|
|
### 2. Run Tests
|
|
```bash
|
|
./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
|
|
```bash
|
|
./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:
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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:
|
|
```bash
|
|
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`:
|
|
|
|
```yaml
|
|
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
|
|
|
|
- [MOBILE_COMPATIBILITY.md](./MOBILE_COMPATIBILITY.md) - Mobile compatibility strategy
|
|
- [Playwright Device Emulation](https://playwright.dev/docs/emulation)
|
|
- [Material-UI Responsive Design](https://mui.com/material-ui/customization/breakpoints/)
|