🍪 Cookie Clicker Bot

A Selenium bot that plays Cookie Clicker for you: it clicks the big cookie, buys the most expensive upgrade it can afford every 5 seconds and prints the cookies per second after 5 minutes. It is the solution to day 48 of Udemy's 100 Days of Code: The Complete Python Pro Bootcamp, written for course participants who want to compare solutions and for visitors who browse for ideas.

📚 Table of Contents

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

🧭 Overview

The bot follows the five steps of the lecture:

1. Get to know the game.
2. Click the cookie as fast as possible, after dismissing the language selection.
3. Every 5 seconds buy the most expensive upgrade you can afford.
4. After 5 minutes stop and print cookies/second.
5. Tweak the strategy (check interval, buy one or buy all affordable).

The five steps in pictures

Step	Screenshot
1. Get to know the game
2. Click the cookie
3. Buy the most expensive affordable upgrade
4. Stop after 5 minutes, print cookies/second
5. Tweak the strategy

What each step taught is explained in the wiki, in English, Danish and Bahasa Malaysia (the same pages are in docs/wiki/).

The repository is organised like this:

Folder or file	What it is for
src/cookie_clicker_bot/	The bot. domain/ holds the rules (parsing, choosing the upgrade) with no Selenium, application/ runs the game loop, infrastructure/ drives the browser, constants.py holds every constant
tests/	pytest tests; the unit tests need no browser
docs/	Project documents, wiki pages (English, Danish, Bahasa Malaysia) and the screenshots of the lecture steps
Dockerfile	A Linux image with headless Chromium for real-browser runs and screenshots
Doxyfile	Doxygen configuration for the source comments

📋 Requirements

• Python 3.13 or newer.
• Selenium (the only runtime dependency; it is installed by pip and finds the browser driver itself).
• Google Chrome or Chromium to run the bot on your own machine.
• pytest and pytest-cov for the tests (development extra only).
• Docker, only if you want to run the bot or take screenshots without opening a window on your desktop.
• Doxygen, only to build the source documentation.

🛠️ Setup

Create a local virtual environment, upgrade pip and install the project with the test tools:

python -m venv .venv

Activate it:

# Linux and macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

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

▶️ Run

With the environment active:

cookie-clicker-bot

or, without installing the command:

python -m cookie_clicker_bot

The bot plays for 5 minutes, then prints one line on standard output, for example cookies/second: 18.9. What it did (clicks, purchases, time) is logged on standard error. Options:

Option	What it does	Default
--duration SECONDS	How long to play	300
--interval SECONDS	Time between upgrade checks (greater than 0)	5
--buy-all	Buy every affordable upgrade, most expensive first, instead of one	off
--headless	Run Chromium without a window	off (on in Docker)
--screenshot PATH	Save a screenshot when the run ends	none
--screenshot-start PATH	Save a screenshot before the first click	none

To keep your desktop free, run it in the Docker container (headless Chromium). Options go after the image name:

docker build -t cookie-clicker-bot .
docker run --rm cookie-clicker-bot
docker run --rm cookie-clicker-bot --headless --interval 10

🧪 Tests

python -m pytest

Coverage of the logic modules is checked with python -m pytest --cov. Tests that need a real browser are marked browser and run in the Docker container; all other tests need neither a browser nor the network.

Build the source documentation with Doxygen:

doxygen Doxyfile

📄 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
Artifact registry	Where each artifact type lives, the next version, the PO language and domain
Domain dictionary	The PO terms and the IT terms
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

---