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.

Lab 9 UAT Scenarios

The following acceptance test scenarios were defined in Lab 9 and are the initial scenario set for E2E automation planning:

Test Case ID	Scenario	Module	Automation Status
TC_AUTH_2	Google OAuth Login	AUTH	Planned; should remain skipped until OAuth dependencies are ready
TC_TAG_1	Keyword Tagging on Story Creation	TAG	Planned
TC_MEDIA_2	Audio Transcription Review Before Posting	MEDIA	Planned
TC_TAG_2	Keyword Tagging UI During Story Creation	TAG	Planned
TC_STORY_5	Anonymous Story Sharing	STORY	Planned
TC_MAP_2	Multi-Location Story Display on Map	MAP	Planned
TC_DASH_1	User Dashboard View Count	DASH	Planned; should remain skipped until view-count tracking is available
TC_BADGE_1	First Post Badge Awarded	BADGE	Planned; should remain skipped until badge dependencies are ready

The existing web UAT skeleton also includes TC_AUTH_1 as a runnable baseline registration and login flow. It is not one of the Lab 9 example scenarios, but it provides the template for implementing the Lab 9 scenarios.

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.