🚀 Cookie Clicker Bot

A Selenium bot that plays Cookie Clicker for five minutes: it clicks the big cookie, buys upgrades and reports its cookies per second (CPS). It is the day 48 project of Udemy's 100 Days of Code: The Complete Python Pro Bootcamp, written to be read, run and compared by other course participants.

📚 Table of Contents

• Overview
• Requirements
• Setup
• Run
• Tests
• License
• Links
• Appendix: Project documents

🧭 Overview

The bot follows the five steps of the lecture. Every step is one function with the assignment's name, and every step has a screenshot taken by the bot itself in a headless Chromium inside Docker.

Step	Function	What it does
1	open_game, select_language	Opens the game and picks English
2	click_cookie	Clicks the big cookie
3	get_cookie_count	Reads the number of cookies
4	get_store_items, choose_upgrade, buy_upgrade	Buys the most expensive upgrade it can afford
5	run_bot, get_cps	Plays for 300 seconds and reports the CPS

Lecture step screenshots

Step 1: open the game and choose a language

Step 2: click the big cookie

Step 3: read the cookie count

Step 4: buy the first upgrade

Step 5: the five-minute result

In the run that made these screenshots the bot reached 16.6 cookies per second after 300 seconds. Your number will differ: it depends on the speed of your machine and the network.

Parts of the repository

Folder	Holds
src/cookie_clicker_bot/domain/	Game rules without Selenium: number parsing and the purchase choice
src/cookie_clicker_bot/application/	The lecture step functions and the ports they need
src/cookie_clicker_bot/infrastructure/	The Selenium adapter and the clock
src/cookie_clicker_bot/presentation/	The command line entry points
src/cookie_clicker_bot/constants.py	All constants: address, element ids, timings
tests/	pytest tests that need no browser
docker/	The Docker image used for headless runs and screenshots
docs/	Project documents, screenshots and the wiki

The only runtime dependency is selenium; a bot cannot drive a browser without it (see ADR-0001 in docs/adr/).

📋 Requirements

• Python 3.13 or newer.
• Google Chrome (Selenium Manager downloads the matching driver). Not needed to run the tests.
• Docker, only to repeat the headless run and the screenshots.
• Doxygen, only to build the API documentation.

🛠️ Setup

Create a local virtual environment, upgrade pip and install the project with its development tools.

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Linux and macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Leave the environment with deactivate. The .venv folder is ignored by git.

▶️ Run

With the virtual environment active, start the bot. A Chrome window opens and plays for five minutes, then the bot prints the CPS and closes the browser:

python -m cookie_clicker_bot

Useful options:

python -m cookie_clicker_bot --headless
python -m cookie_clicker_bot --duration 60

To repeat the headless run and the screenshots without touching your desktop, use Docker. The screenshots and a steps.json summary land in runs/ (the ones in docs/images/ came from such a run):

docker build -t cookie-clicker-bot -f docker/Dockerfile .
docker run --rm -v "$(pwd)/runs:/runs" cookie-clicker-bot --out /runs

To build the API documentation from the Doxygen comments, run doxygen Doxyfile; the result is in docs/api/html/.

🧪 Tests

The tests use fakes for the game and the clock, so they need neither Chrome nor the network:

python -m pytest
python -m ruff check src tests
python -m mypy src tests

📄 License

GNU Affero General Public License v3.0, see LICENSE.

🔗 Links

• Repository
• Documentation
• Issue tracker

📎 Appendix: Project documents

The documents a newcomer needs, in reading order.

Document	What it tells you
AGENTS.md	The rules AI agents follow in this repository
Business Case	Why the project exists, its scope and success criteria
Stakeholder Analysis	Who is involved; the stakeholder IDs used for owners and reviewers
Project Plan	The gateways and their schedule
Milestones	One document per gateway: Go/No-Go criteria and tasks
ADR-0001	Why Selenium is the one runtime dependency
Artifact registry	Where each artifact type lives, the next version, the PO language and domain
Traceability matrix	How the artifacts link and when each was last reviewed
Framework README	The framework this project uses
Framework changelog	What changed in each framework release

---