E2E Testing

E2E Testing

This page defines the starting scope and technical plan for end-to-end testing of the Local History Story Map web and mobile applications. It follows the acceptance testing structure introduced in Lab 9 and keeps E2E tests focused on user-visible behavior rather than implementation details.

Scope

E2E tests validate complete user flows against a running application stack. Tests should exercise the frontend through the same UI that users interact with and verify that the expected state is visible after each step.

The initial E2E scope covers high-value flows from the current UAT scenarios:

• Authentication flows
• Story creation and retrieval flows
• Map and location-based story discovery
• Media upload and transcription review flows
• Anonymous story sharing flows
• Dashboard and badge flows when their backend and frontend dependencies are ready
• Tagging and search flows when their backend and frontend dependencies are ready

New or unstable features may be represented as skipped tests until their dependencies are available.

Test Case Structure

E2E test cases should reuse the Lab 9 UAT schema:

• Test Case ID: TC_<MODULE>_<N>
• Title: short behavior-focused title
• Module: AUTH, STORY, MAP, SEARCH, MEDIA, SOCIAL, DASH, MOD, BADGE, or TAG
• Automated: Yes or No
• Requirement(s): linked requirement IDs
• Preconditions: required user state, seed data, or service configuration
• Test Data / Fixtures: accounts, stories, media files, or seeded datasets
• Test Steps: step number, action, selector, input, expected result
• Post-condition: expected system state after execution
• Notes: domain-specific execution notes

Automated E2E implementations should map test descriptions to runnable test files without embedding unnecessary low-level implementation details into the UAT document.

Frameworks

Web

• Framework: Playwright
• Browser target: Chromium
• Execution mode: headless in CI, headed mode available for local debugging
• Location: frontend/tests/uat/
• Configuration: frontend/playwright.config.js
• Base URL: UAT_BASE_URL, defaulting to http://localhost:3000
• Reports: HTML and JUnit reports

Web E2E tests should prefer page.getByTestId() and stable data-testid attributes over CSS or XPath selectors.

Mobile

• Framework: Appium
• Platform target: Android
• App target: generated debug APK
• Execution mode: local-only at the start
• Planned location: frontend/tests/mobile-e2e/

Mobile E2E tests should launch the Android APK, switch to the WebView context when needed, and reuse the same data-testid selector strategy as web E2E tests where the Capacitor WebView exposes the same DOM.

Required local environment variables:

• ANDROID_APP_PATH: path to the APK under test, for example frontend/android/app/build/outputs/apk/debug/app-debug.apk
• APPIUM_SERVER_URL: Appium server URL, for example http://127.0.0.1:4723
• MOBILE_API_BASE_URL: backend API base URL baked into the Capacitor web assets before APK build
• ANDROID_DEVICE_NAME: emulator or device name used by Appium

Execution Environment

E2E tests should run against an application environment that matches the development or staging stack as closely as possible. No mocks should be used for user acceptance flows unless a third-party provider cannot be exercised reliably.

For web E2E:

• Start the full stack.
• Wait for backend health.
• Run Playwright tests against the frontend base URL.

For mobile E2E:

• Prepare Capacitor web assets with MOBILE_API_BASE_URL.
• Build the Android debug APK.
• Start an Android emulator locally.
• Start the Appium server locally.
• Run Appium tests against ANDROID_APP_PATH.

Mobile E2E CI integration is not part of the initial scope. It should be added only after the local Appium skeleton and first smoke tests are reliable.

Selector Strategy

Tests should use stable, explicit selectors:

• Prefer data-testid for buttons, inputs, page states, notifications, and repeated list items.
• Keep selector names aligned across web and mobile when the same UI is rendered in the Capacitor WebView.
• Avoid selectors based only on styling, layout, or generated class names.

Test Data Strategy

E2E tests should be deterministic:

• Use seeded accounts when a flow requires existing data.
• Generate unique users or story titles for create flows.
• Clean up test-created data when feasible.
• Avoid fixed sleeps; use explicit waits for visible UI states, network completion, or route changes.
• Keep each test focused on a single user-facing behavior.

Reporting

E2E reports should be machine-readable and human-readable:

• Web E2E: Playwright HTML report and JUnit XML report.
• Mobile E2E: JUnit XML report, with screenshots or Appium logs retained for failures when available.

Report names should make the test layer clear, for example uat-report.xml for web and mobile-e2e-report.xml for Appium.