Name That Yankee

"Name That Yankee" is a web-based trivia game where users test their knowledge of New York Yankees players based on career statistics and highlights. The project features a public-facing website with historical puzzles and a playable quiz interface, supported by an automated pipeline for generating new trivia content.

Project Overview

• Purpose: A daily trivia game for New York Yankees fans, providing an archive of historical puzzles and a playable quiz interface.
• Architecture:
  • Frontend: A static website built with HTML, CSS, and Vanilla JavaScript.
  • Data Layer: Player data and archives are managed through JS files (all_players.js) and individual HTML pages for each trivia date.
  • Automation (Page Generator): A Python-based toolset that automates the creation of new puzzle pages, including scraping stats, processing images, and generating HTML.
• Deployment: Hostable as a static site (e.g., GitHub Pages).

Technology Stack

• Frontend: HTML5, CSS3, JavaScript (ES Modules).
• Automation (Python): Python 3.x, Selenium, Pillow (image processing), Pydantic, Beautiful Soup 4.
• Testing:
  • Frontend: Vitest (with jsdom).
  • Automation: Pytest.
• CI/CD: GitHub Actions.

Key Files & Directories

• index.html: The main archives page and entry point for the site.
• quiz.html: The interactive quiz interface.
• all_players.js: Central data file containing player information and historical records.
• style.css: Primary stylesheet for the entire application.
• page-generator/: Root directory for the Python automation suite.
  • main.py: Entry point for the automation CLI.
  • automation/: Modules for image processing, player search, and git integration.
  • html_generator.py: Logic for generating new trivia page HTML.
• images/: Contains puzzle clues (webp) and player images.
• automation_config.json: Persistent settings for the automation pipeline.

Building and Running

Development Environment Setup

To set up a new environment (e.g., a new laptop) for full development and testing:

1. System Dependencies:

   • Java 21+: Required for the Firebase/Firestore emulator.
   • Python 3.11+ & venv: Required for the automation pipeline and backend tests.
   • Node.js 20+: Required for frontend tests and development server.

2. Initialize Environment:

   # 1. Create and activate Python virtual environment
   python3 -m venv .venv
   source .venv/bin/activate
   
   # 2. Install Python dependencies
   pip install -r requirements.txt -r test_requirements.txt
   
   # 3. Install Node.js dependencies
   npm install
   
   # 4. Install Playwright browsers (for UI tests)
   playwright install chromium --with-deps

Troubleshooting New Environments

• Java 21 Errors: If npm test fails with a Java version error, ensure you have Java 21 installed. If you have a local compatible JDK, run: export JAVA_HOME=/path/to/your/jdk && export PATH=$JAVA_HOME/bin:$PATH before running tests.
• python3-venv missing: On some Linux systems, you may need to install the python3-venv package manually if the bootstrap script fails to create the .venv.
• Playwright Dependencies: If UI tests fail to launch the browser, run npx playwright install-deps to ensure all system-level libraries are present.

Website

• Local Development: Run python3 serve.py to start the custom local development server. Avoid generic servers (like npx serve . or python3 -m http.server) because they do not support GitHub Pages' clean routing behavior (e.g., extensionless URLs like /quiz or /analytics will return 404s).
• Local Development: Run python3 serve.py to start the custom local development server. Avoid generic servers (like npx serve . or python3 -m http.server) because they do not support GitHub Pages' clean routing behavior (e.g. extensionless URLs like /quiz or /analytics will return 404s).

Automation (Page Generator)

To use the puzzle generation tools:

1. Activate environment:

   source .venv/bin/activate

2. Run automation:

   # Standard workflow
   python page-generator/main.py --automate-workflow [screenshot_path]
   
   # Configure automation
   python page-generator/main.py --config

For more detailed information on the automation workflow, see README_AUTOMATION.md and AUTOMATION_SUMMARY.md.

Testing

Always ensure your environment is fully set up before running tests. The primary entry point for running all tests is:

./run_tests.sh

Test Layers

1. Frontend & Security Tests (Vitest): Logic for scoring, UI, and Firestore security rules. Run with npm test.
2. E2E & Accessibility Tests (Playwright): Site structure, search/filter, dynamic SEO canonical tags, and WCAG compliance. Run with pytest test_yankee_site.py test_seo_dynamic.py.
3. Automation Unit Tests (Pytest): Logic for scraping, image processing, and HTML generation. Run with pytest tests/unit/.
4. Integration Tests: End-to-end workflow of page generation tools. Run with pytest test_automation.py.

See TEST_README.md for more details.

Development Conventions

• HTML Generation: New puzzles are generated as individual HTML files named YYYY-MM-DD.html. These are automatically linked in index.html by the page generator.
• Images: Puzzle clues should be in WEBP format and named clue-YYYY-MM-DD.webp. Player images follow a similar naming convention or are referenced in all_players.js.
• State Management: The frontend uses localStorage to track scores and solved puzzles (see index.html and quiz.html scripts).
• Game Integrity & Redirect Funnel: Player detail pages contain redirection logic (in js/detail.js) that redirects users to quiz.html if they haven't completed that day's puzzle. This is an intentional game mechanic to protect the quiz experience and prevent users from going directly to the answers. Never modify or bypass this redirection funnel without explicit coordination.

License

Name That Yankee Quiz © 2025 by Scott Zager is licensed under CC BY-NC-SA 4.0.