# Manual QA Scenarios

These scenarios complement the automated integration, unit, and Playwright suites. They are written for a reviewer preparing the demo for a public crowdfunding update and focus on the moments that matter to backers: collecting, predicting, learning trivia, unlocking progress, and coming back tomorrow.

## Preparation

1. Start the API and web app using the commands in `README.md`.
2. Open the web app in a clean browser profile or private window.
3. Keep the browser devtools console visible during at least one full run.
4. If using a deployed preview, confirm the frontend is configured to call that preview API, not a stale local URL.
5. Use the same demo persona throughout the run so XP, badges, and leaderboard movement are observable.

Suggested persona:

- Name: `Demo Lion`
- Fan focus: England
- Goal: collect teams/stadiums, answer trivia, predict a giant killing, and climb the leaderboard.

## Scenario 1: First load and empty/new-user state

Purpose: prove that a visitor can understand the product immediately.

Steps:

1. Open the app.
2. Wait for the dashboard/passport content to load.
3. Inspect any empty collection or “not started” areas.
4. Navigate through the main visible sections.

Pass criteria:

- The page has a clear top-level heading or product title.
- Loading state is visible before data-backed content appears on slow networks.
- Empty areas explain the next action instead of showing raw blanks.
- No unhandled promise rejection or red runtime overlay appears.
- Keyboard focus starts in a sensible location and visible focus styles are present.

## Scenario 2: Collect a team

Purpose: prove that the passport collection loop works end to end.

Steps:

1. Find a team collection action, preferably England for the demo story.
2. Activate the collect action with a mouse.
3. Observe XP, collection count, challenge progress, and any badge notification.
4. Try collecting the same team again if the UI still exposes the action.
5. Refresh the page.

Pass criteria:

- The team becomes visibly collected.
- XP and/or progress changes once.
- Repeating the action does not duplicate XP, badges, or collection entries.
- The collected state persists after refresh.
- The UI gives a clear disabled, collected, or already-owned state.

## Scenario 3: Collect a stadium

Purpose: prove that the virtual travel/stadium completion fantasy is represented.

Steps:

1. Find the stadium collection area.
2. Collect one stadium.
3. Continue collecting stadiums until challenge progress visibly advances.
4. If the seed data allows it quickly, complete the stadium challenge.

Pass criteria:

- Stadium count increases.
- Challenge progress uses understandable copy such as `1 / N`.
- Completing the requirement unlocks or completes a visible reward state.
- Long stadium names do not overflow on mobile width.

## Scenario 4: Watch or collect a match

Purpose: prove that match memories can be recorded.

Steps:

1. Find a seeded match.
2. Mark it as watched/collected.
3. Inspect related progress such as “watch all England matches” or group completion.
4. Refresh the app.

Pass criteria:

- The match changes to a watched/collected state.
- Any connected challenge updates immediately.
- Refresh preserves the state.
- Repeating the action remains idempotent.

## Scenario 5: Answer trivia correctly and incorrectly

Purpose: prove daily retention content works and cannot be exploited.

Steps:

1. Open the trivia area.
2. Answer one question with the option believed to be correct.
3. Observe feedback, XP, challenge progress, and badge notifications.
4. If another question is available, answer incorrectly.
5. Attempt to answer an already answered question again.

Pass criteria:

- The user receives immediate correctness feedback.
- Correct answers award the configured reward once.
- Incorrect answers are recorded gracefully and do not crash the flow.
- Already answered questions cannot be farmed repeatedly for XP.
- Feedback is available to screen readers through visible text or live-region style status copy.

## Scenario 6: Submit a prediction

Purpose: prove predictions are connected to gamification.

Steps:

1. Open the prediction area.
2. Choose a match and submit a realistic score or winner prediction.
3. Submit an upset/giant-killing style prediction if the demo content exposes one.
4. Observe XP, challenge progress, and passport memory state.
5. Try resubmitting or editing the same prediction.

Pass criteria:

- The submitted prediction is shown back to the user.
- Prediction-related challenge progress changes.
- Invalid or incomplete prediction forms show validation errors.
- Resubmission follows a clear rule: either update-in-place or reject duplicate, without double-counting XP.
- Form controls have labels and can be operated by keyboard.

## Scenario 7: Complete a challenge and unlock a badge

Purpose: prove the achievement system is action-driven.

Steps:

1. Identify a challenge that is close to completion.
2. Perform the remaining required action.
3. Observe completion state, badge unlock, XP change, and any notification.
4. Refresh the page and revisit the badge/challenge area.

Pass criteria:

- Completion is triggered by the action without manual refresh.
- Badge/challenge appears in completed/unlocked state after refresh.
- If multiple achievements unlock at once, the UI remains readable.
- The same completed challenge cannot be claimed repeatedly unless designed as a repeatable challenge.

## Scenario 8: Leaderboard movement

Purpose: prove competition and return motivation are visible.

Steps:

1. Record the demo user’s current XP/rank.
2. Perform one or more XP-awarding actions.
3. Reopen or refresh the leaderboard.
4. Compare the new rank and XP total.

Pass criteria:

- XP total changes consistently with action rewards.
- Rank updates or remains stable for an understandable reason.
- Ties are presented deterministically.
- Empty leaderboard states are friendly if the store is reset.

## Scenario 9: Network and backend failure handling

Purpose: prove the demo fails gracefully under real-world conditions.

Steps:

1. Load the page successfully.
2. Stop the API or block API requests in devtools.
3. Trigger a collection/trivia/prediction action.
4. Restart/unblock the API.
5. Retry the action.

Pass criteria:

- The user sees a clear error message.
- The app does not lose already loaded content unnecessarily.
- Buttons recover from pending/disabled state after failure.
- Retry succeeds without duplicate side effects.
- Console does not show uncaught promise errors.

## Scenario 10: Responsive smoke pass

Purpose: prove the app is demoable on common crowdfunding update devices.

Viewports:

- 375 × 667 mobile portrait
- 390 × 844 modern mobile
- 768 × 1024 tablet portrait
- 1024 × 768 tablet landscape
- 1440 × 900 desktop

Pass criteria:

- No horizontal page scroll at mobile widths.
- Primary call-to-action buttons remain visible and tappable.
- Cards wrap cleanly without text overlap.
- Leaderboard rows remain readable.
- Prediction and trivia forms do not require precision clicking.
- Sticky/fixed elements do not cover form controls.

## Scenario 11: Keyboard accessibility pass

Purpose: prove non-mouse users can complete the core loop.

Steps:

1. Reload the app.
2. Use `Tab`, `Shift+Tab`, `Enter`, and `Space` only.
3. Collect one item.
4. Answer one trivia question.
5. Submit one prediction if a select/radio/input flow is available.
6. Navigate to the leaderboard.

Pass criteria:

- Focus is always visible.
- Focus order follows the visual order.
- Interactive cards expose real buttons/links or correct ARIA semantics.
- Modal/toast/banner content does not trap focus unless intentionally modal.
- Status changes are readable without relying on color alone.

## Scenario 12: Public-demo rehearsal

Purpose: verify the release can be presented smoothly.

Steps:

1. Follow `docs/demo-script.md` from start to finish.
2. Speak the actions aloud as if recording a two-minute update.
3. Capture screenshots for the crowdfunding update.
4. Run the automated E2E demo test after the rehearsal.

Pass criteria:

- Script completes in under ten minutes.
- The story is understandable to a non-technical football fan.
- Screenshots show visible progress and reward moments.
- Automated tests still pass after the manual demo path.