Set up the repository, run the test suite, and open a pull request.
git clone https://github.com/imutkarsht/Chess_analyzer.git cd Chess_analyzer uv venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate uv pip install -r requirements-dev.txt
With standard pip:
python -m venv venv source venv/bin/activate pip install -r requirements-dev.txt
requirements-dev.txt adds pytest, pytest-qt, coverage, and Ruff to the runtime dependencies.
python main.py
Chess_analyzer/
├── main.py # Entry point
├── build.spec # PyInstaller packaging
├── src/
│ ├── constants.py # Version, defaults, URLs, providers
│ ├── config/settings_schema.py # Settings registry (Qt-free)
│ ├── backend/ # Zero Qt imports
│ │ ├── analysis/ # Analyzer, engine, classifier, metrics, tactics, books
│ │ ├── api/ # Chess.com and Lichess clients
│ │ ├── cache/ # API cache facade
│ │ ├── engine/ # Stockfish downloader and validator
│ │ ├── models/ # Cross-layer models
│ │ ├── services/ # LLM and feedback
│ │ ├── storage/ # SQLite, repositories, migrations, PGN, backup
│ │ └── updater/ # GitHub releases and installers
│ ├── gui/
│ │ ├── main_window/ # Window plus focused mixins
│ │ ├── views/ # Analyze, Explore, History, Metrics, Settings
│ │ ├── analysis/ # Analysis panel, move list, Coach, Tactics, variations
│ │ ├── import_workspace/ # Multi-game import table and batch actions
│ │ ├── share/ # Shareable report card renderer and dialog
│ │ ├── board/ # Board, eval bar, piece themes
│ │ ├── components/ # Shared component library, one facade
│ │ ├── dialogs/ # Load game, wizard, feedback, errors, updates
│ │ ├── engine_lines/ # Shared live engine session
│ │ ├── metrics/ # Drill-down and chart helpers
│ │ ├── theme/ + styles.py # Palettes and QSS generators
│ │ └── utils/ # Debounce, shortcuts, widget factories
│ └── utils/ # Config, logger, paths, resources, secrets
├── tests/ # pytest suite
├── assets/ # Icons, pieces, openings, sounds
└── installers/ # Platform packaging
For a layer-by-layer description, see Architecture.
The suite uses pytest with pytest-qt, pytest-mock, and branch coverage.
pytest tests/ # full suite pytest tests/backend/test_analyzer.py # one module pytest tests/gui/test_explorer_replay.py # one GUI file
Headless Linux or CI without a display:
QT_QPA_PLATFORM=offscreen pytest tests/
The whole suite is designed to finish in under 20 seconds and must pass offline.
| Path | Covers |
|---|---|
tests/conftest.py | Shared qapp, engine, PGN, temp database, and temp config fixtures |
tests/backend/ | Analyzer, engine manager, PGN parser, models, APIs, LLM service, storage, books, downloader |
tests/gui/ | Board, analysis panel, Coach, explorer, history, metrics, settings, shortcuts, theme, window lifecycle |
tests/utils/ | Config and path helpers |
time.sleep(), QTest.qWait(), or real network calls to wait for work.worker.run()) and assert on emitted signals.tmp_path; never touch the real database, config, secrets, or logs.@pytest.mark.parametrize over near-duplicate tests.MainWindow instances for simple branches.ruff check .
Zero errors is the gate. Formatting is not a required check, and unrelated files should not be reformatted.
X | None, list[T], dict[K, V].print(). Use from src.utils.logger import logger.Styles.COLOR_* and the style generators.src.gui.components instead of raw Qt widgets.src/config/settings_schema.py.src/utils/path_utils.py for paths.pytest tests/ --cov=src --cov-branch --cov-report=term-missing
Backend and utility code must stay at or above the 85% branch-coverage floor in pyproject.toml.
GUI modules are excluded deliberately. If coverage drops, add a meaningful test instead of lowering
the floor.
pyinstaller build.spec
Output lands in dist/ as ChessAnalyzerPro.app on macOS, ChessAnalyzerPro.exe on Windows, and a
ChessAnalyzerPro binary on Linux. Platform installers live under installers/.
Copy .env.sample to .env for local development:
GROQ_API_KEY=your_groq_api_key
LICHESS_TOKEN=your_lichess_personal_token
| Variable | Purpose |
|---|---|
GROQ_API_KEY | AI Coach provider during development |
LICHESS_TOKEN | Authenticated Lichess imports and online explorer |
Never commit real keys, and never let a local .env turn a unit test into a live request.
master.ruff check . and pytest tests/.CHANGELOG.md for user-visible changes.Use Conventional Commits (feat:, fix:, refactor:, test:, docs:).
Questions go to GitHub issues with the
question label.
Download Chess Analyzer Pro for Windows, macOS, or Linux. 100% free, private, and open-source.