> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/igorek05m/daily-geogame/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing guide

> Learn how to test Daily GeoGame and ensure quality contributions

Daily GeoGame currently focuses on manual testing and code quality checks. This guide explains how to test your changes before submitting them.

## Testing philosophy

While Daily GeoGame doesn't have automated tests yet, quality is ensured through:

* **Manual testing**: Playing the game and testing features interactively
* **Linting**: ESLint catches common errors and enforces code style
* **Build validation**: TypeScript compiler catches type errors
* **Code review**: Pull requests are reviewed for quality and correctness

## Running the development server

The best way to test your changes is to run the game locally:

```bash theme={null}
pnpm dev
```

This starts the Next.js development server with Turbopack at [http://localhost:3000](http://localhost:3000). The server includes:

* Hot module replacement for instant feedback
* Error overlay for debugging
* Fast refresh for component changes

### Development workflow

<Steps>
  <Step title="Make code changes">
    Edit components, utilities, or API routes in your code editor.
  </Step>

  <Step title="Check the browser">
    The page automatically refreshes. Check if your changes work as expected.
  </Step>

  <Step title="Test edge cases">
    Try unusual inputs, rapid interactions, or error conditions.
  </Step>

  <Step title="Check browser console">
    Look for errors, warnings, or unexpected behavior in the console.
  </Step>
</Steps>

## Linting

Run ESLint to catch common issues, enforce code style, and detect potential bugs:

```bash theme={null}
pnpm lint
```

ESLint checks for:

* TypeScript type issues
* React best practices and hooks rules
* Next.js specific patterns
* Code style consistency

### Fixing lint errors

When you run `pnpm lint`, you'll see any issues that need to be fixed:

<CodeGroup>
  ```bash Example output (with errors) theme={null}
  ✖ 3 problems (2 errors, 1 warning)
    2 errors and 0 warnings potentially fixable with the `--fix` option.

  app/components/Map.tsx
    12:5  error  'country' is assigned a value but never used  @typescript-eslint/no-unused-vars
    23:10 warning Missing 'key' prop for element in iterator  react/jsx-key
  ```

  ```bash Example output (passing) theme={null}
  ✔ No ESLint warnings or errors
  ```
</CodeGroup>

Fix each issue by editing the relevant files. Some issues can be auto-fixed, but most require manual correction.

## Build testing

Before submitting a pull request, ensure the production build succeeds:

```bash theme={null}
pnpm build
```

This command:

* Compiles TypeScript to JavaScript
* Type-checks all files
* Optimizes the application for production
* Generates static pages and assets
* Reports any build errors or warnings

### What to check

<Accordion title="Build output details">
  A successful build shows:

  ```bash theme={null}
  ✓ Compiled successfully
  ✓ Linting and checking validity of types
  ✓ Collecting page data
  ✓ Generating static pages
  ✓ Finalizing page optimization

  Route (app)                              Size     First Load JS
  ┌ ○ /                                    5.2 kB         92.1 kB
  └ ○ /api/country                         0 B                0 B
      /api/daily                           0 B                0 B
      /api/progress                        0 B                0 B
      /api/stats                           0 B                0 B

  ○  (Static)  prerendered as static content
  ```

  If the build fails, fix the errors before committing.
</Accordion>

## Manual testing checklist

When testing your changes, verify these core features still work correctly:

### Making guesses

* [ ] Country autocomplete shows suggestions as you type
* [ ] Selecting a country from dropdown works
* [ ] Guess appears in the guess list
* [ ] Correct guess shows success message
* [ ] Incorrect guess shows on map with color gradient
* [ ] Duplicate guesses are prevented

### Hint progression

* [ ] First hint appears immediately
* [ ] New hint reveals after each incorrect guess
* [ ] Hints display correct data (climate, terrain, GDP, etc.)
* [ ] All 6 hints can be revealed
* [ ] Last hint shows properly formatted country facts

### Map interactions

* [ ] Map loads and displays correctly
* [ ] Zoom in/out works smoothly
* [ ] Pan/drag moves the map
* [ ] Guessed countries highlight in color
* [ ] Neighboring countries highlight
* [ ] Color gradient shows proximity (closer = greener)
* [ ] Target country highlights on win

### Statistics tracking

* [ ] Stats modal opens and closes
* [ ] Current streak displays correctly
* [ ] Longest streak updates on wins
* [ ] Win/loss record increments
* [ ] Stats persist between page refreshes
* [ ] Session ID is created and stored

### Date navigation

* [ ] Clicking previous date loads yesterday's game
* [ ] Today's game is accessible
* [ ] Previous game progress is preserved
* [ ] Can't navigate to future dates
* [ ] Date display shows correct format

### Session persistence

* [ ] Refreshing page preserves game state
* [ ] Guesses remain after reload
* [ ] Hints stay revealed
* [ ] Win/loss state persists
* [ ] Stats survive browser restart

### Responsive design

* [ ] Layout works on mobile (\< 640px)
* [ ] Layout works on tablet (640px - 1024px)
* [ ] Layout works on desktop (> 1024px)
* [ ] Map is usable on touch devices
* [ ] Modals display correctly on all sizes

## Areas that need testing

Pay special attention to these areas, which are prone to issues:

<AccordionGroup>
  <Accordion title="Map rendering and interactions">
    The SVG map is complex and can have issues with:

    * Performance on low-end devices
    * Touch gestures (pinch-zoom, pan)
    * Country highlighting logic
    * Color gradient calculations
    * Neighbor detection accuracy
  </Accordion>

  <Accordion title="Date and timezone handling">
    Daily games change at midnight UTC:

    * Test across different timezones
    * Verify correct country for each date
    * Check date navigation near midnight
    * Ensure consistent game state
  </Accordion>

  <Accordion title="Session and state management">
    Progress is saved locally and synced:

    * Test with cookies disabled
    * Verify session ID creation
    * Check state persistence
    * Test multiple browser tabs
    * Verify stats synchronization
  </Accordion>

  <Accordion title="Country data and hints">
    Hints come from external data sources:

    * Verify all countries have complete data
    * Check for missing or null values
    * Test hint formatting and display
    * Ensure factbook data is accurate
  </Accordion>
</AccordionGroup>

## How to report bugs

If you find a bug while testing, report it on GitHub:

<Steps>
  <Step title="Check existing issues">
    Search [existing issues](https://github.com/igorek05m/daily-geogame/issues) to avoid duplicates.
  </Step>

  <Step title="Create a new issue">
    If the bug hasn't been reported, create a new issue with:

    * Clear title describing the problem
    * Steps to reproduce
    * Expected vs actual behavior
    * Browser and device information
    * Screenshots or video if helpful
  </Step>

  <Step title="Provide context">
    Include:

    * What you were trying to do
    * Which date/country was active
    * Any error messages in console
    * Whether it's reproducible
  </Step>
</Steps>

### Example bug report

```markdown theme={null}
Title: Map doesn't highlight neighboring countries on mobile

Description:
When playing on mobile (iPhone Safari), incorrect guesses appear
on the map but neighboring countries don't highlight as they do
on desktop.

Steps to reproduce:
1. Open game on iPhone Safari
2. Make an incorrect guess
3. Observe the map

Expected: Neighbors should highlight in light color
Actual: Only the guessed country highlights

Environment:
- Device: iPhone 14 Pro
- OS: iOS 17.2
- Browser: Safari
- Date: 2026-03-02
```

## Future testing improvements

As the project grows, we plan to add:

* **Unit tests**: For utilities and helper functions
* **Integration tests**: For API routes and database operations
* **E2E tests**: For critical user flows
* **Visual regression tests**: To catch UI changes
* **Automated testing**: CI/CD pipeline for pull requests

Contributions to improve testing infrastructure are very welcome! See the [contributing guide](/development/contributing) to get started.