# Mobile App Visual Component Testing Guide

**Last Updated:** 2026-03-26

## Overview

This guide provides comprehensive testing procedures for the mobile app visual switcher component. Use this guide to verify all functionality works correctly after implementation or updates.

## Quick Test Script

**Location:** `v2/scripts/dev-helpers/test-mobile-app-visual.js`

**Usage:**
1. Open `/mitarbeiter-app` or `/branchen/gastronomie` (viewport ≥1024px for sticky checks)
2. Open browser console (F12)
3. Copy entire contents of `test-mobile-app-visual.js`
4. Paste into console and press Enter
5. Run: `testMobileAppVisual()`

The script will automatically check:
- Required elements exist
- `data-visual-id` / `visual-{id}` pairs (Mitarbeiter-app or Gastronomie IDs)
- CSS classes and sticky rules (expects header-safe `top`, not legacy `50%` + transform)
- Current active visual

## Manual Testing Checklist

### 1. Page Load Scenarios

**Test 1.1: Features Section Visible on Load**
- [ ] Navigate to `/mitarbeiter-app`
- [ ] Scroll to features section (`#mobile-app-features`)
- [ ] Verify visual appears when first section enters viewport
- [ ] Verify correct visual is active (should be "Schichtplanung")
- [ ] Check browser console for errors

**Test 1.2: Features Section Below Fold**
- [ ] Navigate to `/mitarbeiter-app`
- [ ] Don't scroll (features section below viewport)
- [ ] Verify visual does NOT appear
- [ ] Scroll down to features section
- [ ] Verify visual appears when first section enters viewport
- [ ] Check browser console for errors

**Test 1.3: Direct Link to Section**
- [ ] Navigate to `/mitarbeiter-app#section-zeiterfassung`
- [ ] Verify correct visual is active (should be "Zeiterfassung")
- [ ] Verify visual is positioned correctly
- [ ] Check browser console for errors

### 2. Scroll Through Sections

**Test 2.1: Slow Scroll**
- [ ] Start at top of page
- [ ] Slowly scroll down through all 4 sections
- [ ] Verify visual switches correctly:
  - [ ] Section 1: Schichtplanung visual
  - [ ] Section 2: Zeiterfassung visual
  - [ ] Section 3: Urlaub visual
  - [ ] Section 4: Dokumente visual
- [ ] Verify visual scrolls smoothly with page scroll
- [ ] Verify visual centers with active section

**Test 2.2: Fast Scroll**
- [ ] Start at top of page
- [ ] Quickly scroll down through all 4 sections
- [ ] Verify visual switches correctly (no flickering)
- [ ] Verify transitions complete properly
- [ ] Check for performance issues (lag, jank)

**Test 2.3: Scroll Up**
- [ ] Scroll to bottom of features section
- [ ] Scroll back up through sections
- [ ] Verify visual switches correctly in reverse order
- [ ] Verify visual scrolls smoothly upward
- [ ] Verify visual centers with active section

### 3. Boundary Behavior

**Test 3.1: Visual Appears at First Section**
- [ ] Scroll to just before features section
- [ ] Verify visual does NOT appear
- [ ] Scroll down until first section enters viewport
- [ ] Verify visual appears when first section becomes visible
- [ ] Verify correct visual is active (Schichtplanung)

**Test 3.2: Visual Disappears After Last Section**
- [ ] Scroll to last section (Dokumente)
- [ ] Verify visual is visible
- [ ] Scroll past last section (completely out of viewport)
- [ ] Verify visual disappears/hides
- [ ] Verify transform is reset

**Test 3.3: No Visual Before Features Section**
- [ ] Scroll to top of page (above features section)
- [ ] Verify visual does NOT appear
- [ ] Verify no transform is applied
- [ ] Check browser console for errors

**Test 3.4: No Visual After Features Section**
- [ ] Scroll past features section completely
- [ ] Verify visual does NOT appear
- [ ] Verify transform is reset
- [ ] Check browser console for errors

### 4. Scroll Direction

**Test 4.1: Scroll Down (Visual Moves Down)**
- [ ] Position at first section
- [ ] Note visual position
- [ ] Scroll down slowly
- [ ] Verify visual moves DOWN (positive translateY)
- [ ] Verify visual follows section center

**Test 4.2: Scroll Up (Visual Moves Up)**
- [ ] Position at last section
- [ ] Note visual position
- [ ] Scroll up slowly
- [ ] Verify visual moves UP (negative translateY)
- [ ] Verify visual follows section center

**Test 4.3: Visual Centers with Active Section**
- [ ] Scroll to middle of any section
- [ ] Verify visual center aligns with section center
- [ ] Verify visual is vertically centered in viewport
- [ ] Check transform value in DevTools

### 5. Crossfade Transitions

**Test 5.1: Smooth Transitions**
- [ ] Scroll slowly between sections
- [ ] Verify smooth opacity crossfade (0.5s)
- [ ] Verify no flickering
- [ ] Verify transitions complete before next switch

**Test 5.2: Rapid Switching**
- [ ] Scroll quickly between sections
- [ ] Verify transitions don't overlap
- [ ] Verify no visual glitches
- [ ] Verify final visual is correct

**Test 5.3: Transition Timing**
- [ ] Use DevTools to inspect transitions
- [ ] Verify transition duration: 0.5s
- [ ] Verify easing: cubic-bezier(0.4, 0, 0.2, 1)
- [ ] Verify will-change: opacity is set

### 6. Responsive Behavior

**Test 6.1: Desktop (≥1024px)**
- [ ] Set viewport width ≥1024px
- [ ] Verify sticky positioning is enabled
- [ ] Verify visual scrolls dynamically
- [ ] Verify transform is applied
- [ ] Verify visual is centered vertically

**Test 6.2: Mobile (<1024px)**
- [ ] Set viewport width <1024px
- [ ] Verify sticky positioning is disabled
- [ ] Verify visuals stack vertically
- [ ] Verify no transform is applied
- [ ] Verify all visuals are visible (opacity: 1)
- [ ] Verify proper spacing between visuals

**Test 6.3: Tablet (768px - 1023px)**
- [ ] Set viewport width between 768px and 1023px
- [ ] Verify mobile behavior (sticky disabled)
- [ ] Verify visuals stack vertically
- [ ] Verify layout is responsive

### 7. Window Resize

**Test 7.1: Resize from Desktop to Mobile**
- [ ] Start with desktop viewport (≥1024px)
- [ ] Verify visual is sticky and scrolling
- [ ] Resize to mobile (<1024px)
- [ ] Verify sticky is disabled
- [ ] Verify visuals stack vertically
- [ ] Verify transform is reset
- [ ] Verify no layout breaks

**Test 7.2: Resize from Mobile to Desktop**
- [ ] Start with mobile viewport (<1024px)
- [ ] Verify visuals are stacked
- [ ] Resize to desktop (≥1024px)
- [ ] Verify sticky is enabled
- [ ] Verify visual repositions correctly
- [ ] Verify scroll positioning works

**Test 7.3: Resize During Scroll**
- [ ] Scroll to middle of features section
- [ ] Resize window while scrolling
- [ ] Verify visual repositions correctly
- [ ] Verify no layout breaks
- [ ] Verify scroll positioning recalculates

### 8. Browser Compatibility

**Test 8.1: Chrome**
- [ ] Test in Chrome (latest version)
- [ ] Verify visual switching works
- [ ] Verify scroll positioning works
- [ ] Verify transitions are smooth
- [ ] Check console for errors

**Test 8.2: Firefox**
- [ ] Test in Firefox (latest version)
- [ ] Verify visual switching works
- [ ] Verify scroll positioning works
- [ ] Verify transitions are smooth
- [ ] Check console for errors

**Test 8.3: Safari**
- [ ] Test in Safari (latest version)
- [ ] Verify visual switching works
- [ ] Verify scroll positioning works
- [ ] Verify transitions are smooth
- [ ] Check console for errors

**Test 8.4: Edge**
- [ ] Test in Edge (latest version)
- [ ] Verify visual switching works
- [ ] Verify scroll positioning works
- [ ] Verify transitions are smooth
- [ ] Check console for errors

### 9. Console Errors

**Test 9.1: No JavaScript Errors**
- [ ] Open browser console
- [ ] Navigate to `/mitarbeiter-app`
- [ ] Scroll through all sections
- [ ] Verify no JavaScript errors
- [ ] Verify no warnings (except expected ones)

**Test 9.2: Intersection Observer**
- [ ] Check console for Intersection Observer errors
- [ ] Verify observer is created successfully
- [ ] Verify observer callbacks fire correctly
- [ ] Check for any observer warnings

**Test 9.3: Performance**
- [ ] Open DevTools Performance tab
- [ ] Record while scrolling through sections
- [ ] Verify smooth 60fps scrolling
- [ ] Check for layout thrashing
- [ ] Verify no memory leaks

### 10. Edge Cases

**Test 10.1: Multiple Sections Visible**
- [ ] Scroll to position where 2 sections are partially visible
- [ ] Verify correct visual is active (highest intersection ratio)
- [ ] Verify visual switches correctly

**Test 10.2: Rapid Scroll**
- [ ] Scroll very quickly through all sections
- [ ] Verify visual switches correctly
- [ ] Verify no visual glitches
- [ ] Verify final state is correct

**Test 10.3: Scroll to Top**
- [ ] Scroll to bottom of features section
- [ ] Scroll back to top quickly
- [ ] Verify visual disappears correctly
- [ ] Verify transform is reset

**Test 10.4: Page Refresh**
- [ ] Scroll to middle of features section
- [ ] Refresh page
- [ ] Verify visual initializes correctly
- [ ] Verify correct visual is active

## Debugging

The switcher uses **scroll** + `requestAnimationFrame` (see `CONFIG.referenceLineRatio` in `v2/js/mobile-app-visual-switcher.js`). There is no `CONFIG.debug` flag; add temporary `console.log` in `pickActiveVisualId` / `updateActiveFromViewport` if needed, then remove before commit.

**Layout contract:** spacer, sticky `top` token, and section padding — [mobile-app-features-layout.md](mobile-app-features-layout.md).

## Common Issues & Solutions

### Visual Not Appearing
- **Check:** Features section is in viewport
- **Check:** First section has `.mobile-app-text-section-first` class
- **Check:** Visual wrapper exists
- **Check:** JavaScript is loaded
- **Solution:** Enable debug mode and check console

### Visual Not Sticking (Desktop)
- **Check:** Viewport width ≥1024px
- **Check:** `.mobile-visual-container-wrapper` has `position: sticky` and resolved `top` from `--mobile-app-visual-sticky-top`
- **Check:** No conflicting `transform` on the wrapper (should be `none`)

### Visual Switching Incorrectly
- **Check:** `data-visual-id` on each `.mobile-app-text-section` matches `id="visual-{id}"` on each `.mobile-visual`
- **Check:** `CONFIG.referenceLineRatio` (default `0.3`) — lower moves the “decision line” upward in the viewport (earlier section switches)
- **Check:** Multiple sections visible — algorithm prefers the section that **contains** the reference Y, else closest center

## Performance Targets

- **FPS:** Maintain 60fps during scroll
- **LCP:** Visual should not delay LCP
- **CLS:** No layout shift during transitions
- **Memory:** No memory leaks during extended use

## Related Files

- **JavaScript:** `v2/js/mobile-app-visual-switcher.js`
- **CSS:** `v2/css/mobile-app-components.css`
- **HTML:** `v2/pages/product_mobile_app.php`, `v2/pages/branchen_gastronomie_neu.php`
- **Test Script:** `v2/scripts/dev-helpers/test-mobile-app-visual.js`
- **Layout contract:** [mobile-app-features-layout.md](mobile-app-features-layout.md)
- **Documentation:** `docs/content/pages/product-pages/mobile-app-documentation.md`

## Support

For issues or questions:
1. Run test script: `testMobileAppVisual()`
2. Check browser console for errors
3. Review [mobile-app-features-layout.md](mobile-app-features-layout.md) and this guide
4. Check implementation documentation