Resolve pending commit links

StoreItem and choose_upgrade, get_store_items, buy_upgrade, get_cps,
run_bot with a Clock port, main and python -m cookie_clicker_bot. 74
offline tests. Reviewed in RC-012.

Task: MIL-003#1
Task: MIL-003#2
Task: MIL-003#3
Task: MIL-003#4
Task: MIL-003#5
Task: MIL-003#6
Closes #13
Closes #14
Closes #15
Closes #16
Closes #17
Closes #18

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,md}]
+indent_size = 2

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Project specific
+# Local secrets, personal use only (never imported by the project)
+.env
+# Generated API documentation (doxygen Doxyfile)
+/docs/api/
+# Scratch output of local and Docker runs; published screenshots live in docs/images/
+/runs/
+# AI prompt log: this repository is public
+/docs/ai-prompts/

Doxyfile

@@ -0,0 +1,374 @@
+# Doxyfile 1.15.0
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "Cookie Clicker Bot"
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = "Selenium bot for Cookie Clicker (Udemy 100 Days of Code, day 48)"
+PROJECT_LOGO           =
+PROJECT_ICON           =
+OUTPUT_DIRECTORY       = docs/api
+CREATE_SUBDIRS         = NO
+CREATE_SUBDIRS_LEVEL   = 8
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+JAVADOC_BANNER         = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+PYTHON_DOCSTRING       = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                =
+OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_JAVA   = YES
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+OPTIMIZE_OUTPUT_SLICE  = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+MARKDOWN_STRICT        = YES
+TOC_INCLUDE_HEADINGS   = 6
+MARKDOWN_ID_STYLE      = DOXYGEN
+AUTOLINK_SUPPORT       = YES
+AUTOLINK_IGNORE_WORDS  =
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+NUM_PROC_THREADS       = 1
+TIMESTAMP              = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_UNDOC_NAMESPACES  = YES
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = SYSTEM
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_HEADERFILE        = YES
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+EXTERNAL_TOOL_PATH     =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = NO
+WARN_IF_UNDOC_ENUM_VAL = NO
+WARN_LAYOUT_FILE       = YES
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LINE_FORMAT       = "at line $line of file $file"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = src README.md
+INPUT_ENCODING         = UTF-8
+INPUT_FILE_ENCODING    =
+FILE_PATTERNS          = *.py
+RECURSIVE              = YES
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE = README.md
+IMPLICIT_DIR_DOCS      = YES
+FORTRAN_COMMENT_AFTER  = 72
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+CLANG_ASSISTED_PARSING = NO
+CLANG_ADD_INC_PATHS    = YES
+CLANG_OPTIONS          =
+CLANG_DATABASE_PATH    =
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_CODE_FOLDING      = YES
+HTML_COPY_CLIPBOARD    = YES
+HTML_PROJECT_COOKIE    =
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_FEEDURL         =
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+SITEMAP_URL            =
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = YES
+PAGE_OUTLINE_PANEL     = YES
+FULL_SIDEBAR           = NO
+ENUM_VALUES_PER_LINE   = 4
+SHOW_ENUM_VALUES       = NO
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+OBFUSCATE_EMAILS       = YES
+HTML_FORMULA_FORMAT    = png
+FORMULA_FONTSIZE       = 10
+FORMULA_MACROFILE      =
+USE_MATHJAX            = NO
+MATHJAX_VERSION        = MathJax_2
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        =
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         =
+MAKEINDEX_CMD_NAME     = makeindex
+LATEX_MAKEINDEX_CMD    = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_BIB_STYLE        = plainnat
+LATEX_EMOJI_DIRECTORY  =
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_EXTRA_FILES        =
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to Sqlite3 output
+#---------------------------------------------------------------------------
+GENERATE_SQLITE3       = NO
+SQLITE3_OUTPUT         = sqlite3
+SQLITE3_RECREATE_DB    = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             =
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+#---------------------------------------------------------------------------
+# Configuration options related to diagram generator tools
+#---------------------------------------------------------------------------
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_COMMON_ATTR        = "fontname=Helvetica,fontsize=10"
+DOT_EDGE_ATTR          = "labelfontname=Helvetica,labelfontsize=10"
+DOT_NODE_ATTR          = "shape=box,height=0.2,width=0.4"
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+UML_MAX_EDGE_LABELS    = 10
+DOT_UML_DETAILS        = NO
+DOT_WRAP_THRESHOLD     = 17
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DIR_GRAPH_MAX_DEPTH    = 1
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+DIA_PATH               =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+PLANTUMLFILE_DIRS      =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+MSCGEN_TOOL            =
+MSCFILE_DIRS           =

docs/adr/adr-0001-selenium-runtime-dependency.md

@@ -0,0 +1,56 @@
+# Selenium as the single runtime dependency
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0001 |
+| CrossReference | [BC-001], [SA-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version (reviewed in RC-009) | [ad3334f] |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+The assignment is to automate the Cookie Clicker game in a real browser with Selenium ([BC-001], objective O1). GitHub viewers (S03) asked for no runtime dependencies (concern CN-006 in [SA-001]), and the Business Case constraint says to avoid runtime dependencies unless needed. The bot must read the page and click elements, so something has to drive a browser.
+
+Options evaluated:
+
+1. **Selenium** as the one runtime dependency. It is what the assignment and the course use, and Selenium Manager downloads a matching driver.
+2. **No dependency**, driving Chrome through the DevTools protocol with the standard library only. This needs a hand-written WebSocket client and protocol code, which is long, fragile and unreadable for S02.
+3. **Playwright**. A comparable dependency, but not the library of the assignment, so S02 could not compare solutions.
+4. **Selenium plus a threading helper** (the author's earlier solution used `continuous_threading`). A second dependency for something the standard library `threading` or a single loop already does.
+
+## Decision
+
+Selenium is the only runtime dependency; pytest, ruff and mypy are development dependencies, and everything else uses the standard library.
+
+## Consequences
+
+**Positive:**
+
+- The code matches the assignment, so S02 can compare solutions directly.
+- Only one package is installed to run the bot (`pip install .`).
+- The decision logic is behind a port, so tests need neither Selenium nor a browser.
+
+**Negative:**
+
+- S03's wish for no dependencies is met only in part; the README states why Selenium is needed.
+- Running the bot needs Chrome installed (Selenium Manager fetches the driver); the Docker image covers this for the screenshots.
+- Performance Efficiency: Selenium calls cost milliseconds each, which limits the clicks per second.
+
+## Affected Artifacts
+
+- [BC-001] — fixes the runtime dependency list for success criterion 4.
+- [SA-001] — records the mitigation of the conflict between CN-006 and the assignment.
+
+---
+
+[BC-001]: ../business-case.md
+[SA-001]: ../stakeholder-analysis.md
+[ad3334f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/ad3334fa13c4261c3d034fbffcc7b43fe95fbb31

docs/artifact-registry.md

@@ -15,9 +15,9 @@ document of a type. `Primary File` may contain a glob (e.g.
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
 | MIL | Milestone / Gateway | docs/milestones/mil-*.md | 006 |
-| ADR | Architecture Decision Record | docs/adr/adr-*.md | 0001 |
+| ADR | Architecture Decision Record | docs/adr/adr-*.md | 0002 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 009 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 013 |
 
 ## Languages
 

docs/sqa/reviews/rc-009-adr-0001-selenium-runtime-dependency.md

@@ -0,0 +1,55 @@
+# SQA Review Record
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-009 |
+| CrossReference | [ADR-0001], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [ad3334f] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: ADR-0001 ([ADR-0001])
+- Checklist used: [QC-ADR-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ID ADR-0001 matches the file name adr-0001 and is the first. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Context names the forces (S03 concern, constraint) and four options. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options evaluated. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | One sentence, matches option 1. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Positive and Negative lists present. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Performance Efficiency cost of Selenium calls named. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | BC-001 and SA-001 are linked and in CrossReference. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | Single row with Change and Commit columns. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Not superseded. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | Abbreviation Selenium is a product name; others spelled out. |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Status Accepted. |
+
+## Overall Verdict
+
+Go - All Mandatory criteria pass. Stand-in review, not independent.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[ADR-0001]: ../../adr/adr-0001-selenium-runtime-dependency.md
+[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
+[ad3334f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/ad3334fa13c4261c3d034fbffcc7b43fe95fbb31

docs/sqa/reviews/rc-010-mil-001-source.md

@@ -0,0 +1,62 @@
+# SQA Review Record
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-010 |
+| CrossReference | [MIL-001], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [ad3334f] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: source of milestone MIL-001 (src/cookie_clicker_bot, tests/, pyproject.toml) ([MIL-001])
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | snake_case modules, UPPER_SNAKE constants. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose (RUN_DURATION_SECONDS). |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check src tests` reports no findings; ruff configured in pyproject.toml. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Test functions annotated with -> None; constants annotated. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | N-A | No exception handling in this milestone. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | None present. |
+| 7 | Files, locks and connections are managed with context managers | N-A | No files or connections yet. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Module docstrings use Doxygen @file/@brief. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | N-A | No logging yet. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | Plain technical task; no Design Class Diagram exists or is required. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | tests/unit/test_constants.py runs offline; `pytest` passes 2 tests. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | mypy strict configured; no Any. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | selenium>=4.25 is the only runtime dependency (ADR-0001). |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Timing constants defined once in constants.py. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | Layer packages exist; no cross imports yet. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | N-A | No classes yet. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | domain, application, infrastructure and presentation under src/; unit, integration and e2e under tests/. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | All names English, snake_case, no spaces. |
+
+## Overall Verdict
+
+Go - All Mandatory criteria pass or are not applicable to this skeleton. Stand-in review, not independent.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[MIL-001]: ../../milestones/mil-001-project-setup.md
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[ad3334f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/ad3334fa13c4261c3d034fbffcc7b43fe95fbb31

docs/sqa/reviews/rc-011-mil-002-source.md

@@ -0,0 +1,62 @@
+# SQA Review Record
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-011 |
+| CrossReference | [MIL-002], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [68c4391] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: source of milestone MIL-002 (open_game, select_language, click_cookie, get_cookie_count, parser, Selenium adapter) ([MIL-002])
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | snake_case modules and functions, PascalCase classes, UPPER_SNAKE constants. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose: parse_game_number, wait_for_element, ELEMENT_TIMEOUT_SECONDS. |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` clean; no suppressions. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | All signatures annotated, including -> None; mypy strict passes. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No bare except; ValueError and UnreadableNumberError are raised with a message. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; no builtin shadowed. |
+| 7 | Files, locks and connections are managed with context managers | N-A | The browser is released by SeleniumGame.close(); the composition root in MIL-003 calls it in a finally block. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Public modules, classes and functions have Doxygen docstrings (@brief, @param, @return). |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | N-A | No logging yet; added with the run loop in MIL-003. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | Plain technical tasks; no Design Class Diagram exists or is required. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 33 tests (unit and integration) run offline with a fake game and a fake driver; positive, negative, boundary and edge cases covered. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | mypy --strict: no issues in 22 files; no Any. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | selenium is declared and is the only runtime dependency. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | URL, ids and number words are defined once in constants.py. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | domain imports only constants; application imports domain and its own port; only infrastructure/selenium_game.py imports selenium; no cycles. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | GamePort is a narrow Protocol (4 methods); SeleniumGame receives its driver (dependency inversion); each module has one purpose. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | domain, application (ports, use_cases), infrastructure and presentation under src/; unit, integration and e2e under tests/. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | All names English, snake_case, no spaces. |
+
+## Overall Verdict
+
+Go - All Mandatory criteria pass or are not applicable; the live-game behaviour is verified in MIL-004. Stand-in review, not independent.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[MIL-002]: ../../milestones/mil-002-bot-core-open-and-click.md
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[68c4391]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/68c439137f13299e20cf6271e392365d9f5371c4

docs/sqa/reviews/rc-012-mil-003-source.md

@@ -0,0 +1,62 @@
+# SQA Review Record
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-012 |
+| CrossReference | [MIL-003], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [cb8e5ed] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: source of milestone MIL-003 (store, choose_upgrade, buy_upgrade, get_cps, run_bot, main) ([MIL-003])
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | PEP 8 casing throughout. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose (choose_upgrade, STORE_CHECK_INTERVAL_SECONDS). |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` clean, `ruff format` applied, no suppressions. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | All signatures annotated; mypy --strict passes on 33 files. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | Specific exceptions (ValueError, UnreadableNumberError); a failed purchase is logged and stops the buying loop instead of being swallowed. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults, no shadowed builtins. |
+| 7 | Files, locks and connections are managed with context managers | Pass | The browser is released in a finally block in cli.main (tested when run_bot raises). |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Doxygen docstrings on all public items. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | Progress goes through logging; the only print is the program result `Result : <cps>` in the command line entry point; no secrets are logged. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | Plain technical tasks; no Design Class Diagram exists or is required. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 74 offline tests with a fake game and a fake clock; no sleeps, no network, no browser; positive, negative, boundary, edge, error handling and timing cases. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | mypy --strict clean; no Any. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | selenium remains the only runtime dependency. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Ids, class names, burst size and intervals live in constants.py; decimal parsing is shared by parse_game_number. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | domain imports only constants and errors; application imports domain and ports; selenium only in infrastructure; the CLI is the composition root. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Clock and GamePort are narrow Protocols; run_bot receives both (dependency inversion); one purpose per module. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | Layers under src/ and unit and integration tests under tests/. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | All names English, snake_case, no spaces. |
+
+## Overall Verdict
+
+Go - All Mandatory criteria pass or are not applicable; behaviour against the live game is verified in MIL-004. Stand-in review, not independent.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[MIL-003]: ../../milestones/mil-003-upgrades-and-five-minute-run.md
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[cb8e5ed]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/cb8e5edfbf5acd1d0553568c11be7bbb4c5e5e1c

docs/sqa/traceability-matrix.md

@@ -1,71 +1,79 @@
-# Traceability Matrix
-
-## Metadata
-| Key | Value |
-| --- | --- |
-| ID | TM-001 |
-| CrossReference | [BC-001], [SA-001], [PP-001] |
-
-## Version History
-| Date | Status | Author | Reviewer | Change | Commit |
-| --- | --- | --- | --- | --- | --- |
-| 2026-10-28 | Proposed | Jens Tirsvad Nielsen | <reviewer S-ID> | Initial version | [96a9a78] |
-
----
-
-## Purpose
-
-Tracks backward/forward links between artifact instances so that the Business Case's
-cross-artifact traceability success criterion is measurable. A row is added or
-updated whenever an artifact instance is created or reviewed.
-
-## Traceability Table
-
-| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
-| --- | --- | --- | --- | --- | --- | --- |
-| [BC-001] | BC | en | it | - | [SA-001], [PP-001] | [RC-001] |
-| [SA-001] | SA | en | it | [BC-001] | [PP-001] | [RC-002] |
-| [PP-001] | PP | en | it | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005] | [RC-003] |
-| [MIL-001] | MIL | en | it | [PP-001] | [MIL-002] | [RC-004] |
-| [MIL-002] | MIL | en | it | [MIL-001] | [MIL-003] | [RC-005] |
-| [MIL-003] | MIL | en | it | [MIL-002] | [MIL-004] | [RC-006] |
-| [MIL-004] | MIL | en | it | [MIL-003] | [MIL-005] | [RC-007] |
-| [MIL-005] | MIL | en | it | [MIL-004] | - | [RC-008] |
-
-## Concern Coverage
-
-| Concern (CN-ID) | Views that answer it | Decisions (ADR) | Quality check (TP) | Status |
-| --- | --- | --- | --- | --- |
-| CN-001 | [MIL-003] | - | - | Gap |
-| CN-002 | [BC-001] | - | - | Covered |
-| CN-003 | [MIL-002] | - | - | Covered |
-| CN-004 | [MIL-004] | - | - | Covered |
-| CN-005 | [MIL-001] | - | - | Covered |
-| CN-006 | [MIL-001] | - | - | Covered |
-| CN-007 | [MIL-005] | - | - | Covered |
-
-## Open Inconsistencies
-
-| # | Views | Inconsistency | Found in (RC-ID) | Status | Resolved in |
-| --- | --- | --- | --- | --- | --- |
-| - | - | None found | - | Closed | - |
-
----
-
-[BC-001]: ../business-case.md
-[SA-001]: ../stakeholder-analysis.md
-[PP-001]: ../project-plan.md
-[MIL-001]: ../milestones/mil-001-project-setup.md
-[MIL-002]: ../milestones/mil-002-bot-core-open-and-click.md
-[MIL-003]: ../milestones/mil-003-upgrades-and-five-minute-run.md
-[MIL-004]: ../milestones/mil-004-screenshots-and-readme.md
-[MIL-005]: ../milestones/mil-005-wiki-and-release.md
-[RC-001]: ./reviews/rc-001-business-case.md
-[RC-002]: ./reviews/rc-002-stakeholder-analysis.md
-[RC-003]: ./reviews/rc-003-project-plan.md
-[RC-004]: ./reviews/rc-004-mil-001-project-setup.md
-[RC-005]: ./reviews/rc-005-mil-002-bot-core-open-and-click.md
-[RC-006]: ./reviews/rc-006-mil-003-upgrades-and-five-minute-run.md
-[RC-007]: ./reviews/rc-007-mil-004-screenshots-and-readme.md
-[RC-008]: ./reviews/rc-008-mil-005-wiki-and-release.md
-[96a9a78]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/96a9a78f010ce8ae3fce8d84602317d8b5808a13
+# Traceability Matrix
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | TM-001 |
+| CrossReference | [BC-001], [SA-001], [PP-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-28 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added RC-011 (MIL-002 source review) | [68c4391] |
+| 2026-10-28 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added RC-012 (MIL-003 source review) | [cb8e5ed] |
+
+---
+
+## Purpose
+
+Tracks backward/forward links between artifact instances so that the Business Case's
+cross-artifact traceability success criterion is measurable. A row is added or
+updated whenever an artifact instance is created or reviewed.
+
+## Traceability Table
+
+| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
+| --- | --- | --- | --- | --- | --- | --- |
+| [BC-001] | BC | en | it | - | [SA-001], [PP-001] | [RC-001] |
+| [SA-001] | SA | en | it | [BC-001] | [PP-001] | [RC-002] |
+| [PP-001] | PP | en | it | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005] | [RC-003] |
+| [MIL-001] | MIL | en | it | [PP-001] | [MIL-002], [ADR-0001] | [RC-004], [RC-010] |
+| [MIL-002] | MIL | en | it | [MIL-001] | [MIL-003] | [RC-005], [RC-011] |
+| [MIL-003] | MIL | en | it | [MIL-002] | [MIL-004] | [RC-006], [RC-012] |
+| [MIL-004] | MIL | en | it | [MIL-003] | [MIL-005] | [RC-007] |
+| [MIL-005] | MIL | en | it | [MIL-004] | - | [RC-008] |
+| [ADR-0001] | ADR | - | - | [BC-001], [SA-001], [MIL-001] | - | [RC-009] |
+
+## Concern Coverage
+
+| Concern (CN-ID) | Views that answer it | Decisions (ADR) | Quality check (TP) | Status |
+| --- | --- | --- | --- | --- |
+| CN-001 | [MIL-003] | - | - | Gap |
+| CN-002 | [BC-001] | - | - | Covered |
+| CN-003 | [MIL-002] | - | - | Covered |
+| CN-004 | [MIL-004] | - | - | Covered |
+| CN-005 | [MIL-001] | - | - | Covered |
+| CN-006 | [MIL-001] | [ADR-0001] | - | Covered |
+| CN-007 | [MIL-005] | - | - | Covered |
+
+## Open Inconsistencies
+
+| # | Views | Inconsistency | Found in (RC-ID) | Status | Resolved in |
+| --- | --- | --- | --- | --- | --- |
+| - | - | None found | - | Closed | - |
+
+---
+
+[BC-001]: ../business-case.md
+[ADR-0001]: ../adr/adr-0001-selenium-runtime-dependency.md
+[SA-001]: ../stakeholder-analysis.md
+[PP-001]: ../project-plan.md
+[MIL-001]: ../milestones/mil-001-project-setup.md
+[MIL-002]: ../milestones/mil-002-bot-core-open-and-click.md
+[MIL-003]: ../milestones/mil-003-upgrades-and-five-minute-run.md
+[MIL-004]: ../milestones/mil-004-screenshots-and-readme.md
+[MIL-005]: ../milestones/mil-005-wiki-and-release.md
+[RC-001]: ./reviews/rc-001-business-case.md
+[RC-002]: ./reviews/rc-002-stakeholder-analysis.md
+[RC-003]: ./reviews/rc-003-project-plan.md
+[RC-004]: ./reviews/rc-004-mil-001-project-setup.md
+[RC-005]: ./reviews/rc-005-mil-002-bot-core-open-and-click.md
+[RC-006]: ./reviews/rc-006-mil-003-upgrades-and-five-minute-run.md
+[RC-007]: ./reviews/rc-007-mil-004-screenshots-and-readme.md
+[RC-008]: ./reviews/rc-008-mil-005-wiki-and-release.md
+[RC-009]: ./reviews/rc-009-adr-0001-selenium-runtime-dependency.md
+[RC-010]: ./reviews/rc-010-mil-001-source.md
+[RC-011]: ./reviews/rc-011-mil-002-source.md
+[68c4391]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/68c439137f13299e20cf6271e392365d9f5371c4
+[RC-012]: ./reviews/rc-012-mil-003-source.md
+[cb8e5ed]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory/commit/cb8e5edfbf5acd1d0553568c11be7bbb4c5e5e1c

pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cookie-clicker-bot"
+version = "0.1.0"
+description = "A Selenium bot that plays Cookie Clicker for five minutes and reports its cookies per second (Udemy 100 Days of Code, day 48)."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "AGPL-3.0-or-later"
+license-files = ["LICENSE"]
+keywords = ["selenium", "cookie-clicker", "automation", "udemy", "100-days-of-code"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Education",
+]
+dependencies = [
+    "selenium>=4.25",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[project.scripts]
+cookie-clicker-bot = "cookie_clicker_bot.presentation.cli:main"
+
+[project.urls]
+Repository = "https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-the-coockie-factory"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+mypy_path = "src"

src/cookie_clicker_bot/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Cookie Clicker bot: a Selenium player for the Cookie Clicker browser game.
+"""

src/cookie_clicker_bot/__main__.py

@@ -0,0 +1,13 @@
+"""@file
+@brief Lets `python -m cookie_clicker_bot` start the bot.
+"""
+
+import logging
+
+from cookie_clicker_bot.presentation.cli import main
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    raise SystemExit(main())

src/cookie_clicker_bot/application/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Application layer: the bot's use cases and the ports they need.
+"""

src/cookie_clicker_bot/application/ports/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Ports: what the application needs from the outside world.
+"""

src/cookie_clicker_bot/application/ports/clock.py

@@ -0,0 +1,15 @@
+"""@file
+@brief The port through which the bot tells the time.
+"""
+
+from typing import Protocol
+
+
+class Clock(Protocol):
+    """@brief A monotonic clock. The system clock implements it."""
+
+    def monotonic(self) -> float:
+        """@brief Return seconds from a fixed but arbitrary start, never going back.
+        @return The seconds.
+        """
+        ...

src/cookie_clicker_bot/application/ports/game_port.py

@@ -0,0 +1,42 @@
+"""@file
+@brief The port through which the bot sees and operates the game.
+"""
+
+from typing import Protocol
+
+
+class GamePort(Protocol):
+    """@brief A running game page. The Selenium adapter implements it."""
+
+    def open_page(self, url: str) -> None:
+        """@brief Load the page at the address.
+        @param url The address of the game.
+        """
+        ...
+
+    def wait_for_element(self, element_id: str) -> None:
+        """@brief Block until the element is on the page.
+        @param element_id The HTML id of the element.
+        """
+        ...
+
+    def click_element(self, element_id: str) -> None:
+        """@brief Click the element the way a user does.
+        @param element_id The HTML id of the element.
+        """
+        ...
+
+    def read_text(self, element_id: str) -> str:
+        """@brief Return the visible text of the element.
+        @param element_id The HTML id of the element.
+        @return The text as shown on the page.
+        """
+        ...
+
+    def read_attribute(self, element_id: str, attribute: str) -> str:
+        """@brief Return an attribute of the element.
+        @param element_id The HTML id of the element.
+        @param attribute The attribute name, for example "class".
+        @return The value, or an empty string when the attribute is absent.
+        """
+        ...

src/cookie_clicker_bot/application/use_cases/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Use cases of the bot, one function per lecture step.
+"""

src/cookie_clicker_bot/application/use_cases/bot_core.py

@@ -0,0 +1,51 @@
+"""@file
+@brief Lecture steps 1 to 3: open the game, click the cookie, read the count.
+"""
+
+from cookie_clicker_bot.application.ports.game_port import GamePort
+from cookie_clicker_bot.constants import (
+    BIG_COOKIE_ID,
+    COOKIE_COUNTER_ID,
+    GAME_URL,
+    LANGUAGE_BUTTON_PREFIX,
+    LANGUAGE_CODE,
+)
+from cookie_clicker_bot.domain.number_parsing import parse_game_number
+
+
+def open_game(game: GamePort) -> None:
+    """@brief Load the game and wait until it asks for a language.
+    @param game The game page to operate.
+    """
+    game.open_page(GAME_URL)
+    game.wait_for_element(LANGUAGE_BUTTON_PREFIX + LANGUAGE_CODE)
+
+
+def select_language(game: GamePort) -> None:
+    """@brief Choose the language and wait until the big cookie is playable.
+    @param game The game page to operate.
+    """
+    game.click_element(LANGUAGE_BUTTON_PREFIX + LANGUAGE_CODE)
+    game.wait_for_element(BIG_COOKIE_ID)
+
+
+def click_cookie(game: GamePort, times: int = 1) -> None:
+    """@brief Click the big cookie.
+    @param game The game page to operate.
+    @param times How many clicks to make, zero or more.
+    @throws ValueError When times is negative.
+    """
+    if times < 0:
+        raise ValueError(f"times must not be negative, got {times}")
+    for _ in range(times):
+        game.click_element(BIG_COOKIE_ID)
+
+
+def get_cookie_count(game: GamePort) -> int:
+    """@brief Read how many cookies the bakery has now.
+    @param game The game page to read.
+    @return The number of cookies, rounded to a whole number.
+    @throws UnreadableNumberError When the counter shows no number.
+    """
+    first_line = game.read_text(COOKIE_COUNTER_ID).strip().splitlines()[0]
+    return parse_game_number(first_line)

src/cookie_clicker_bot/application/use_cases/run_bot.py

@@ -0,0 +1,70 @@
+"""@file
+@brief Lecture step 5: play for a set time, buying upgrades, then report the rate.
+"""
+
+import logging
+from decimal import Decimal
+
+from cookie_clicker_bot.application.ports.clock import Clock
+from cookie_clicker_bot.application.ports.game_port import GamePort
+from cookie_clicker_bot.application.use_cases.bot_core import click_cookie
+from cookie_clicker_bot.application.use_cases.store import (
+    buy_upgrade,
+    get_cps,
+    get_store_items,
+)
+from cookie_clicker_bot.constants import (
+    CLICKS_PER_BURST,
+    RUN_DURATION_SECONDS,
+    STORE_CHECK_INTERVAL_SECONDS,
+)
+from cookie_clicker_bot.domain.store_item import choose_upgrade
+
+_logger = logging.getLogger(__name__)
+
+
+def _buy_while_affordable(game: GamePort) -> int:
+    """@brief Buy the best affordable product until none is left or a purchase fails."""
+    bought = 0
+    while (item := choose_upgrade(get_store_items(game))) is not None:
+        if not buy_upgrade(game, item):
+            _logger.warning(
+                "Purchase of product %d did not lower the cookies", item.index
+            )
+            break
+        bought += 1
+        _logger.info("Bought product %d for %d cookies", item.index, item.price)
+    return bought
+
+
+def run_bot(
+    game: GamePort,
+    clock: Clock,
+    duration_seconds: float = RUN_DURATION_SECONDS,
+) -> Decimal:
+    """@brief Click the cookie and buy upgrades until the time is up.
+
+    One loop: a burst of clicks, then, every store check interval, a visit to
+    the store that buys the most expensive affordable product until none is.
+
+    @param game The game page to operate.
+    @param clock The clock that measures the run.
+    @param duration_seconds How long to play, more than zero.
+    @return The cookies per second at the end of the run.
+    @throws ValueError When duration_seconds is zero or negative.
+    """
+    if duration_seconds <= 0:
+        raise ValueError(f"duration_seconds must be positive, got {duration_seconds}")
+    start = clock.monotonic()
+    next_store_check = start + STORE_CHECK_INTERVAL_SECONDS
+    now = start
+    while now - start < duration_seconds:
+        click_cookie(game, CLICKS_PER_BURST)
+        now = clock.monotonic()
+        if now >= next_store_check:
+            _buy_while_affordable(game)
+            next_store_check = now + STORE_CHECK_INTERVAL_SECONDS
+            _logger.info("%.0f of %s seconds played", now - start, duration_seconds)
+    cps = get_cps(game)
+    _logger.info("Run finished at %s cookies per second", cps)
+    return cps

src/cookie_clicker_bot/application/use_cases/store.py

@@ -0,0 +1,62 @@
+"""@file
+@brief Lecture step 4: read the store, buy a product and read the cookies per second.
+"""
+
+from decimal import Decimal
+
+from cookie_clicker_bot.application.ports.game_port import GamePort
+from cookie_clicker_bot.application.use_cases.bot_core import get_cookie_count
+from cookie_clicker_bot.constants import (
+    CLASS_ATTRIBUTE,
+    CPS_ID,
+    CPS_SEPARATOR,
+    ENABLED_CLASS,
+    PRODUCT_COUNT,
+    PRODUCT_ID_PREFIX,
+    PRODUCT_PRICE_ID_PREFIX,
+    UNLOCKED_CLASS,
+)
+from cookie_clicker_bot.domain.number_parsing import (
+    parse_game_decimal,
+    parse_game_number,
+)
+from cookie_clicker_bot.domain.store_item import StoreItem
+
+
+def get_store_items(game: GamePort) -> list[StoreItem]:
+    """@brief Read the products that are visible in the store.
+    @param game The game page to read.
+    @return One item per unlocked product, in store order.
+    @throws UnreadableNumberError When a price shows no number.
+    """
+    items: list[StoreItem] = []
+    for index in range(PRODUCT_COUNT):
+        classes = game.read_attribute(
+            PRODUCT_ID_PREFIX + str(index), CLASS_ATTRIBUTE
+        ).split()
+        if UNLOCKED_CLASS not in classes:
+            continue
+        price = parse_game_number(game.read_text(PRODUCT_PRICE_ID_PREFIX + str(index)))
+        items.append(StoreItem(index, price, ENABLED_CLASS in classes))
+    return items
+
+
+def buy_upgrade(game: GamePort, item: StoreItem) -> bool:
+    """@brief Click a product and check that the purchase went through.
+    @param game The game page to operate.
+    @param item The product to buy.
+    @return True when the cookie count dropped after the click.
+    """
+    before = get_cookie_count(game)
+    game.click_element(PRODUCT_ID_PREFIX + str(item.index))
+    return get_cookie_count(game) < before
+
+
+def get_cps(game: GamePort) -> Decimal:
+    """@brief Read the cookies per second the bakery makes now.
+    @param game The game page to read.
+    @return The rate, with its decimals.
+    @throws UnreadableNumberError When the line shows no number.
+    """
+    text = game.read_text(CPS_ID)
+    return parse_game_decimal(text.partition(CPS_SEPARATOR)[2])

src/cookie_clicker_bot/constants.py

@@ -0,0 +1,72 @@
+"""@file
+@brief Constants shared by every layer of the bot.
+"""
+
+## Seconds the bot plays before it reads the cookies per second (lecture step 5).
+RUN_DURATION_SECONDS: int = 300
+
+## Seconds between two looks at the store while the bot keeps clicking.
+STORE_CHECK_INTERVAL_SECONDS: int = 5
+
+## Seconds to wait for an element before the bot gives up.
+ELEMENT_TIMEOUT_SECONDS: int = 20
+
+## Address of the game the bot plays.
+GAME_URL: str = "https://ozh.github.io/cookieclicker/"
+
+## Element id prefix of the language buttons shown on the first launch.
+LANGUAGE_BUTTON_PREFIX: str = "langSelect-"
+
+## Language the bot chooses (the game's own code for English).
+LANGUAGE_CODE: str = "EN"
+
+## Element id of the big cookie that is clicked to earn cookies.
+BIG_COOKIE_ID: str = "bigCookie"
+
+## Element id of the counter that shows the cookies and the cookies per second.
+COOKIE_COUNTER_ID: str = "cookies"
+
+## Element id of the line that shows the cookies per second.
+CPS_ID: str = "cookiesPerSecond"
+
+## Number of products in the store.
+PRODUCT_COUNT: int = 20
+
+## Element id prefix of a store product; the product index follows.
+PRODUCT_ID_PREFIX: str = "product"
+
+## Element id prefix of the price of a store product; the product index follows.
+PRODUCT_PRICE_ID_PREFIX: str = "productPrice"
+
+## Attribute that holds the CSS classes of an element.
+CLASS_ATTRIBUTE: str = "class"
+
+## Class of a product that is visible in the store.
+UNLOCKED_CLASS: str = "unlocked"
+
+## Class of a product the player can afford.
+ENABLED_CLASS: str = "enabled"
+
+## Clicks on the big cookie between two looks at the clock.
+CLICKS_PER_BURST: int = 20
+
+## Separator between the label and the amount in the cookies per second line.
+CPS_SEPARATOR: str = ":"
+
+## Label printed before the cookies per second at the end of the run.
+RESULT_LABEL: str = "Result"
+
+## Number words the game prints for large amounts, with their value.
+NUMBER_SCALES: dict[str, int] = {
+    "thousand": 10**3,
+    "million": 10**6,
+    "billion": 10**9,
+    "trillion": 10**12,
+    "quadrillion": 10**15,
+    "quintillion": 10**18,
+    "sextillion": 10**21,
+    "septillion": 10**24,
+    "octillion": 10**27,
+    "nonillion": 10**30,
+    "decillion": 10**33,
+}

src/cookie_clicker_bot/domain/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Domain layer: game rules that know nothing about Selenium.
+"""

src/cookie_clicker_bot/domain/errors.py

@@ -0,0 +1,7 @@
+"""@file
+@brief Errors raised by the game rules.
+"""
+
+
+class UnreadableNumberError(ValueError):
+    """@brief Raised when text from the game does not contain a readable number."""

src/cookie_clicker_bot/domain/number_parsing.py

@@ -0,0 +1,38 @@
+"""@file
+@brief Turns the amounts the game prints ("1.234 million") into numbers.
+"""
+
+import re
+from decimal import ROUND_HALF_UP, Decimal
+
+from cookie_clicker_bot.constants import NUMBER_SCALES
+from cookie_clicker_bot.domain.errors import UnreadableNumberError
+
+_AMOUNT = re.compile(r"^\s*(\d[\d,]*(?:\.\d+)?)(?:\s+([a-z]+))?", re.IGNORECASE)
+
+
+def parse_game_decimal(text: str) -> Decimal:
+    """@brief Read the first amount in a text printed by the game, keeping decimals.
+
+    The game groups thousands with commas ("12,345") and writes large amounts
+    with a number word ("1.234 million"). Any other word after the number, such
+    as "cookies", is ignored.
+
+    @param text The text, for example "0.1", "1.234 million" or "12,345 cookies".
+    @return The exact amount.
+    @throws UnreadableNumberError When the text does not start with a number.
+    """
+    match = _AMOUNT.match(text)
+    if match is None:
+        raise UnreadableNumberError(f"No number at the start of {text!r}")
+    value = Decimal(match.group(1).replace(",", ""))
+    return value * NUMBER_SCALES.get((match.group(2) or "").lower(), 1)
+
+
+def parse_game_number(text: str) -> int:
+    """@brief Read the first amount in a text printed by the game as a whole number.
+    @param text The text, for example "1.234 million" or "12,345 cookies".
+    @return The amount, rounded to a whole number.
+    @throws UnreadableNumberError When the text does not start with a number.
+    """
+    return int(parse_game_decimal(text).to_integral_value(rounding=ROUND_HALF_UP))

src/cookie_clicker_bot/domain/store_item.py

@@ -0,0 +1,34 @@
+"""@file
+@brief A product in the store and the rule that picks which one to buy.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class StoreItem:
+    """@brief A product that is visible in the store.
+
+    @param index Position of the product in the store, from zero.
+    @param price Cookies the product costs now.
+    @param is_affordable True when the player has enough cookies to buy it.
+    """
+
+    index: int
+    price: int
+    is_affordable: bool
+
+
+def choose_upgrade(items: Sequence[StoreItem]) -> StoreItem | None:
+    """@brief Pick the most expensive product the player can afford.
+
+    A tie in price goes to the product with the highest index.
+
+    @param items The visible products.
+    @return The product to buy, or None when nothing is affordable.
+    """
+    affordable = [item for item in items if item.is_affordable]
+    if not affordable:
+        return None
+    return max(affordable, key=lambda item: (item.price, item.index))

src/cookie_clicker_bot/infrastructure/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Infrastructure layer: the Selenium adapter that implements the game port.
+"""

src/cookie_clicker_bot/infrastructure/selenium_game.py

@@ -0,0 +1,90 @@
+"""@file
+@brief Selenium adapter for the GamePort, and the factory for the Chrome driver.
+"""
+
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.support import expected_conditions
+from selenium.webdriver.support.ui import WebDriverWait
+
+from cookie_clicker_bot.constants import ELEMENT_TIMEOUT_SECONDS
+
+_HEADLESS_ARGUMENTS: tuple[str, ...] = (
+    "--headless=new",
+    "--no-sandbox",
+    "--disable-dev-shm-usage",
+    "--window-size=1280,1024",
+)
+
+
+class SeleniumGame:
+    """@brief Operates the game page through a Selenium web driver."""
+
+    def __init__(self, driver: WebDriver) -> None:
+        """@brief Create the adapter.
+        @param driver The web driver to operate; the caller owns its creation.
+        """
+        self._driver = driver
+
+    def open_page(self, url: str) -> None:
+        """@brief Load the page at the address.
+        @param url The address of the game.
+        """
+        self._driver.get(url)
+
+    def wait_for_element(self, element_id: str) -> None:
+        """@brief Block until the element is on the page.
+        @param element_id The HTML id of the element.
+        @throws selenium.common.exceptions.TimeoutException When it never appears.
+        """
+        WebDriverWait(self._driver, ELEMENT_TIMEOUT_SECONDS).until(
+            expected_conditions.presence_of_element_located((By.ID, element_id))
+        )
+
+    def click_element(self, element_id: str) -> None:
+        """@brief Click the element with a real click, never a script click.
+
+        The game rate-limits synthetic clicks, so the click must come from the
+        browser the way a user's does.
+
+        @param element_id The HTML id of the element.
+        @throws selenium.common.exceptions.TimeoutException When it never
+            becomes clickable.
+        """
+        element = WebDriverWait(self._driver, ELEMENT_TIMEOUT_SECONDS).until(
+            expected_conditions.element_to_be_clickable((By.ID, element_id))
+        )
+        element.click()
+
+    def read_text(self, element_id: str) -> str:
+        """@brief Return the visible text of the element.
+        @param element_id The HTML id of the element.
+        @return The text as shown on the page.
+        """
+        return self._driver.find_element(By.ID, element_id).text
+
+    def read_attribute(self, element_id: str, attribute: str) -> str:
+        """@brief Return an attribute of the element.
+        @param element_id The HTML id of the element.
+        @param attribute The attribute name, for example "class".
+        @return The value, or an empty string when the attribute is absent.
+        """
+        value = self._driver.find_element(By.ID, element_id).get_attribute(attribute)
+        return value or ""
+
+    def close(self) -> None:
+        """@brief Quit the browser and end the driver session."""
+        self._driver.quit()
+
+
+def create_chrome_driver(headless: bool = False) -> WebDriver:
+    """@brief Build a Chrome web driver.
+    @param headless True to run without a window, for a container or CI.
+    @return The started Chrome driver.
+    """
+    options = webdriver.ChromeOptions()
+    if headless:
+        for argument in _HEADLESS_ARGUMENTS:
+            options.add_argument(argument)
+    return webdriver.Chrome(options=options)

src/cookie_clicker_bot/infrastructure/system_clock.py

@@ -0,0 +1,15 @@
+"""@file
+@brief The Clock port backed by the operating system.
+"""
+
+import time
+
+
+class SystemClock:
+    """@brief Reads the real monotonic clock."""
+
+    def monotonic(self) -> float:
+        """@brief Return seconds from a fixed but arbitrary start, never going back.
+        @return The seconds.
+        """
+        return time.monotonic()

src/cookie_clicker_bot/presentation/__init__.py

@@ -0,0 +1,3 @@
+"""@file
+@brief Presentation layer: the command line entry point.
+"""

src/cookie_clicker_bot/presentation/cli.py

@@ -0,0 +1,57 @@
+"""@file
+@brief Command line entry point and composition root of the bot.
+"""
+
+import argparse
+from collections.abc import Callable, Sequence
+
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from cookie_clicker_bot.application.use_cases.bot_core import open_game, select_language
+from cookie_clicker_bot.application.use_cases.run_bot import run_bot
+from cookie_clicker_bot.constants import RESULT_LABEL, RUN_DURATION_SECONDS
+from cookie_clicker_bot.infrastructure.selenium_game import (
+    SeleniumGame,
+    create_chrome_driver,
+)
+from cookie_clicker_bot.infrastructure.system_clock import SystemClock
+
+DriverFactory = Callable[[bool], WebDriver]
+
+
+def _parse_arguments(argv: Sequence[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="cookie_clicker_bot", description="Play Cookie Clicker."
+    )
+    parser.add_argument(
+        "--headless", action="store_true", help="run Chrome without a window"
+    )
+    parser.add_argument(
+        "--duration",
+        type=float,
+        default=RUN_DURATION_SECONDS,
+        help="seconds to play (default: %(default)s)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    driver_factory: DriverFactory = create_chrome_driver,
+) -> int:
+    """@brief Start the browser, run the bot, print the result and close the browser.
+    @param argv The command line arguments, or None to read them from the process.
+    @param driver_factory Builds the web driver; replaced in tests so no browser starts.
+    @return The process exit code, zero on success.
+    @throws ValueError When the duration is zero or negative.
+    """
+    arguments = _parse_arguments(argv)
+    game = SeleniumGame(driver_factory(arguments.headless))
+    try:
+        open_game(game)
+        select_language(game)
+        cps = run_bot(game, SystemClock(), arguments.duration)
+        print(f"{RESULT_LABEL} : {cps}")
+    finally:
+        game.close()
+    return 0

tests/__init__.py

@@ -0,0 +1,2 @@
+"""@file
+@brief Tests for the Cookie Clicker bot."""

tests/e2e/__init__.py

@@ -0,0 +1,2 @@
+"""@file
+@brief End to end tests (headless Chrome in Docker only)."""

tests/integration/__init__.py

@@ -0,0 +1,2 @@
+"""@file
+@brief Tests that cross a boundary."""

tests/integration/test_selenium_game.py

@@ -0,0 +1,126 @@
+"""@file
+@brief Tests of the Selenium adapter against a hand-written fake driver.
+
+No browser and no network: the fake driver records what the adapter asks for.
+"""
+
+from typing import cast
+
+import pytest
+from selenium.common.exceptions import NoSuchElementException
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from cookie_clicker_bot.infrastructure.selenium_game import SeleniumGame
+
+
+class FakeElement:
+    """@brief An element that counts its real clicks."""
+
+    def __init__(
+        self, text: str = "", attributes: dict[str, str | None] | None = None
+    ) -> None:
+        self.text = text
+        self.attributes = attributes or {}
+        self.clicks = 0
+
+    def get_attribute(self, name: str) -> str | None:
+        return self.attributes.get(name)
+
+    def is_displayed(self) -> bool:
+        return True
+
+    def is_enabled(self) -> bool:
+        return True
+
+    def click(self) -> None:
+        self.clicks += 1
+
+
+class FakeDriver:
+    """@brief A driver with elements by id; it records its calls."""
+
+    def __init__(self, elements: dict[str, FakeElement]) -> None:
+        self.elements = elements
+        self.visited: list[str] = []
+        self.lookups: list[tuple[str, str]] = []
+        self.quit_calls = 0
+
+    def get(self, url: str) -> None:
+        self.visited.append(url)
+
+    def find_element(self, by: str, value: str) -> FakeElement:
+        self.lookups.append((by, value))
+        if value not in self.elements:
+            raise NoSuchElementException(value)
+        return self.elements[value]
+
+    def quit(self) -> None:
+        self.quit_calls += 1
+
+
+def make_game(driver: FakeDriver) -> SeleniumGame:
+    return SeleniumGame(cast(WebDriver, driver))
+
+
+def test_open_page_loads_the_url() -> None:
+    driver = FakeDriver({})
+
+    make_game(driver).open_page("https://example.test/")
+
+    assert driver.visited == ["https://example.test/"]
+
+
+def test_wait_for_element_looks_up_by_id() -> None:
+    driver = FakeDriver({"bigCookie": FakeElement()})
+
+    make_game(driver).wait_for_element("bigCookie")
+
+    assert driver.lookups == [(By.ID, "bigCookie")]
+
+
+def test_read_text_returns_the_element_text() -> None:
+    driver = FakeDriver({"cookies": FakeElement("12 cookies")})
+
+    assert make_game(driver).read_text("cookies") == "12 cookies"
+    assert driver.lookups == [(By.ID, "cookies")]
+
+
+def test_click_element_makes_one_real_click() -> None:
+    element = FakeElement()
+    driver = FakeDriver({"bigCookie": element})
+
+    make_game(driver).click_element("bigCookie")
+
+    assert element.clicks == 1
+    assert all(by == By.ID for by, _ in driver.lookups)
+
+
+def test_read_text_raises_when_element_is_missing() -> None:
+    game = make_game(FakeDriver({}))
+
+    with pytest.raises(NoSuchElementException):
+        game.read_text("missing")
+
+
+def test_read_attribute_returns_the_attribute_value() -> None:
+    driver = FakeDriver(
+        {"product0": FakeElement(attributes={"class": "product unlocked"})}
+    )
+
+    assert make_game(driver).read_attribute("product0", "class") == "product unlocked"
+    assert driver.lookups == [(By.ID, "product0")]
+
+
+def test_read_attribute_returns_empty_string_when_absent() -> None:
+    driver = FakeDriver({"product0": FakeElement()})
+
+    assert make_game(driver).read_attribute("product0", "class") == ""
+
+
+def test_close_quits_the_driver() -> None:
+    driver = FakeDriver({})
+
+    make_game(driver).close()
+
+    assert driver.quit_calls == 1

tests/unit/__init__.py

@@ -0,0 +1,2 @@
+"""@file
+@brief Tests of the pure logic (no browser needed)."""

tests/unit/fakes.py

@@ -0,0 +1,56 @@
+"""@file
+@brief Fakes of the ports for tests that must not start a browser or sleep.
+"""
+
+from collections.abc import Callable
+
+
+class FakeGame:
+    """@brief Records what the bot does and answers reads from dictionaries."""
+
+    def __init__(
+        self,
+        texts: dict[str, str] | None = None,
+        attributes: dict[tuple[str, str], str] | None = None,
+        on_click: Callable[[str], None] | None = None,
+    ) -> None:
+        self.texts: dict[str, str] = texts or {}
+        self.attributes: dict[tuple[str, str], str] = attributes or {}
+        self.on_click = on_click
+        self.opened: list[str] = []
+        self.waited: list[str] = []
+        self.clicked: list[str] = []
+        self.close_calls = 0
+
+    def open_page(self, url: str) -> None:
+        self.opened.append(url)
+
+    def wait_for_element(self, element_id: str) -> None:
+        self.waited.append(element_id)
+
+    def click_element(self, element_id: str) -> None:
+        self.clicked.append(element_id)
+        if self.on_click is not None:
+            self.on_click(element_id)
+
+    def read_text(self, element_id: str) -> str:
+        return self.texts[element_id]
+
+    def read_attribute(self, element_id: str, attribute: str) -> str:
+        return self.attributes.get((element_id, attribute), "")
+
+    def close(self) -> None:
+        self.close_calls += 1
+
+
+class FakeClock:
+    """@brief A clock that moves forward by a fixed step on every reading."""
+
+    def __init__(self, step: float = 1.0) -> None:
+        self.now = 0.0
+        self.step = step
+
+    def monotonic(self) -> float:
+        reading = self.now
+        self.now += self.step
+        return reading

tests/unit/test_bot_core.py

@@ -0,0 +1,66 @@
+"""@file
+@brief Tests of lecture steps 1 to 3 against a fake game.
+"""
+
+import pytest
+
+from cookie_clicker_bot.application.use_cases.bot_core import (
+    click_cookie,
+    get_cookie_count,
+    open_game,
+    select_language,
+)
+from cookie_clicker_bot.constants import (
+    BIG_COOKIE_ID,
+    COOKIE_COUNTER_ID,
+    GAME_URL,
+    LANGUAGE_BUTTON_PREFIX,
+    LANGUAGE_CODE,
+)
+from tests.unit.fakes import FakeGame
+
+LANGUAGE_BUTTON = LANGUAGE_BUTTON_PREFIX + LANGUAGE_CODE
+
+
+def test_open_game_loads_the_url_and_waits_for_the_language_prompt() -> None:
+    game = FakeGame()
+    open_game(game)
+    assert game.opened == [GAME_URL]
+    assert game.waited == [LANGUAGE_BUTTON]
+
+
+def test_select_language_clicks_the_button_and_waits_for_the_cookie() -> None:
+    game = FakeGame()
+    select_language(game)
+    assert game.clicked == [LANGUAGE_BUTTON]
+    assert game.waited == [BIG_COOKIE_ID]
+
+
+@pytest.mark.parametrize("times", [0, 1, 2, 50])
+def test_click_cookie_clicks_the_requested_number_of_times(times: int) -> None:
+    game = FakeGame()
+    click_cookie(game, times)
+    assert game.clicked == [BIG_COOKIE_ID] * times
+
+
+def test_click_cookie_defaults_to_one_click() -> None:
+    game = FakeGame()
+    click_cookie(game)
+    assert game.clicked == [BIG_COOKIE_ID]
+
+
+def test_click_cookie_refuses_a_negative_count() -> None:
+    game = FakeGame()
+    with pytest.raises(ValueError, match="negative"):
+        click_cookie(game, -1)
+    assert game.clicked == []
+
+
+def test_get_cookie_count_reads_the_first_line_of_the_counter() -> None:
+    game = FakeGame({COOKIE_COUNTER_ID: "12,345 cookies\nper second: 3.5"})
+    assert get_cookie_count(game) == 12345
+
+
+def test_get_cookie_count_reads_large_amounts_split_over_lines() -> None:
+    game = FakeGame({COOKIE_COUNTER_ID: "1.234 million\ncookies\nper second: 900"})
+    assert get_cookie_count(game) == 1_234_000

tests/unit/test_cli.py

@@ -0,0 +1,92 @@
+"""@file
+@brief Tests of the command line entry point; no browser is started.
+"""
+
+from decimal import Decimal
+from typing import cast
+
+import pytest
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from cookie_clicker_bot.application.ports.clock import Clock
+from cookie_clicker_bot.application.ports.game_port import GamePort
+from cookie_clicker_bot.constants import RUN_DURATION_SECONDS
+from cookie_clicker_bot.presentation import cli
+
+
+class FakeDriver:
+    def __init__(self) -> None:
+        self.quit_calls = 0
+
+    def quit(self) -> None:
+        self.quit_calls += 1
+
+
+class Recorder:
+    """Stands in for the use cases and the driver factory and records the calls."""
+
+    def __init__(self) -> None:
+        self.driver = FakeDriver()
+        self.headless: list[bool] = []
+        self.durations: list[float] = []
+        self.steps: list[str] = []
+        self.error: Exception | None = None
+
+    def driver_factory(self, headless: bool) -> WebDriver:
+        self.headless.append(headless)
+        return cast(WebDriver, self.driver)
+
+    def open_game(self, game: GamePort) -> None:
+        self.steps.append("open")
+
+    def select_language(self, game: GamePort) -> None:
+        self.steps.append("language")
+
+    def run_bot(self, game: GamePort, clock: Clock, duration: float) -> Decimal:
+        self.steps.append("run")
+        self.durations.append(duration)
+        if self.error is not None:
+            raise self.error
+        return Decimal("12.5")
+
+
+@pytest.fixture
+def recorder(monkeypatch: pytest.MonkeyPatch) -> Recorder:
+    rec = Recorder()
+    monkeypatch.setattr(cli, "open_game", rec.open_game)
+    monkeypatch.setattr(cli, "select_language", rec.select_language)
+    monkeypatch.setattr(cli, "run_bot", rec.run_bot)
+    return rec
+
+
+def test_main_runs_the_steps_prints_the_result_and_closes(
+    recorder: Recorder, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert cli.main([], recorder.driver_factory) == 0
+    assert recorder.steps == ["open", "language", "run"]
+    assert capsys.readouterr().out == "Result : 12.5\n"
+    assert recorder.driver.quit_calls == 1
+
+
+def test_main_uses_the_default_duration_and_a_visible_browser(
+    recorder: Recorder,
+) -> None:
+    cli.main([], recorder.driver_factory)
+    assert recorder.durations == [RUN_DURATION_SECONDS]
+    assert recorder.headless == [False]
+
+
+def test_main_passes_the_headless_flag_and_duration(recorder: Recorder) -> None:
+    cli.main(["--headless", "--duration", "30"], recorder.driver_factory)
+    assert recorder.durations == [30.0]
+    assert recorder.headless == [True]
+
+
+def test_main_closes_the_browser_when_the_run_fails(
+    recorder: Recorder, capsys: pytest.CaptureFixture[str]
+) -> None:
+    recorder.error = RuntimeError("boom")
+    with pytest.raises(RuntimeError, match="boom"):
+        cli.main([], recorder.driver_factory)
+    assert recorder.driver.quit_calls == 1
+    assert capsys.readouterr().out == ""

tests/unit/test_constants.py

@@ -0,0 +1,13 @@
+"""@file
+@brief Guards the timing constants the bot relies on.
+"""
+
+from cookie_clicker_bot import constants
+
+
+def test_run_duration_is_five_minutes() -> None:
+    assert constants.RUN_DURATION_SECONDS == 300
+
+
+def test_store_check_happens_inside_the_run() -> None:
+    assert 0 < constants.STORE_CHECK_INTERVAL_SECONDS < constants.RUN_DURATION_SECONDS

tests/unit/test_number_parsing.py

@@ -0,0 +1,72 @@
+"""@file
+@brief Tests of parse_game_number.
+"""
+
+from decimal import Decimal
+
+import pytest
+
+from cookie_clicker_bot.domain.errors import UnreadableNumberError
+from cookie_clicker_bot.domain.number_parsing import (
+    parse_game_decimal,
+    parse_game_number,
+)
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("0", 0),
+        ("1 cookie", 1),
+        ("15 cookies", 15),
+        ("12,345 cookies", 12345),
+        ("1,234,567", 1234567),
+    ],
+)
+def test_parse_plain_amounts(text: str, expected: int) -> None:
+    assert parse_game_number(text) == expected
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("1.234 million", 1_234_000),
+        ("2 billion", 2_000_000_000),
+        ("1.500 Thousand", 1500),
+        ("3 decillion", 3 * 10**33),
+    ],
+)
+def test_parse_amounts_with_number_word(text: str, expected: int) -> None:
+    assert parse_game_number(text) == expected
+
+
+def test_parse_ignores_unknown_word_after_the_number() -> None:
+    assert parse_game_number("42 bakers") == 42
+
+
+def test_parse_rounds_decimals() -> None:
+    assert parse_game_number("7.6 cookies") == 8
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("0.1", Decimal("0.1")),
+        ("1,234.5", Decimal("1234.5")),
+        ("1.234 million", Decimal("1234000")),
+        ("7", Decimal(7)),
+    ],
+)
+def test_parse_decimal_keeps_the_decimals(text: str, expected: Decimal) -> None:
+    assert parse_game_decimal(text) == expected
+
+
+def test_parse_decimal_rejects_text_without_a_number() -> None:
+    with pytest.raises(UnreadableNumberError):
+        parse_game_decimal("none")
+
+
+@pytest.mark.parametrize("text", ["", "cookies", "-5", "per second: 3"])
+def test_parse_rejects_text_without_a_leading_number(text: str) -> None:
+    with pytest.raises(UnreadableNumberError):
+        parse_game_number(text)

tests/unit/test_run_bot.py

@@ -0,0 +1,107 @@
+"""@file
+@brief Tests of the run loop against a fake game and a fake clock.
+"""
+
+from decimal import Decimal
+
+import pytest
+
+from cookie_clicker_bot.application.use_cases.run_bot import run_bot
+from cookie_clicker_bot.constants import (
+    BIG_COOKIE_ID,
+    CLASS_ATTRIBUTE,
+    CLICKS_PER_BURST,
+    COOKIE_COUNTER_ID,
+    CPS_ID,
+    PRODUCT_ID_PREFIX,
+    PRODUCT_PRICE_ID_PREFIX,
+    RUN_DURATION_SECONDS,
+    STORE_CHECK_INTERVAL_SECONDS,
+)
+from cookie_clicker_bot.domain.errors import UnreadableNumberError
+from tests.unit.fakes import FakeClock, FakeGame
+
+PRODUCT = f"{PRODUCT_ID_PREFIX}0"
+
+
+def make_game(cookies: int = 100, price: int = 15) -> FakeGame:
+    """A store with one affordable product that is spent once, then unaffordable."""
+    game = FakeGame(
+        texts={
+            COOKIE_COUNTER_ID: f"{cookies} cookies",
+            f"{PRODUCT_PRICE_ID_PREFIX}0": str(price),
+            CPS_ID: "per second: 4.5",
+        },
+        attributes={(PRODUCT, CLASS_ATTRIBUTE): "product unlocked enabled"},
+    )
+
+    def spend(element_id: str) -> None:
+        if element_id == PRODUCT:
+            game.texts[COOKIE_COUNTER_ID] = f"{cookies - price} cookies"
+            game.attributes[(PRODUCT, CLASS_ATTRIBUTE)] = "product unlocked disabled"
+
+    game.on_click = spend
+    return game
+
+
+def test_run_bot_returns_the_cps() -> None:
+    assert run_bot(make_game(), FakeClock(), 3) == Decimal("4.5")
+
+
+def test_run_bot_clicks_in_bursts_until_the_duration_is_over() -> None:
+    game = FakeGame(texts={CPS_ID: "per second: 1"})
+    run_bot(game, FakeClock(step=1.0), 3)
+    assert game.clicked == [BIG_COOKIE_ID] * CLICKS_PER_BURST * 3
+
+
+def test_run_bot_stops_after_the_duration() -> None:
+    clock = FakeClock(step=10.0)
+    game = FakeGame(texts={CPS_ID: "per second: 1"})
+    run_bot(game, clock, 25)
+    assert clock.now == 40.0
+
+
+def test_run_bot_does_not_visit_the_store_before_the_interval() -> None:
+    game = make_game()
+    run_bot(game, FakeClock(step=1.0), STORE_CHECK_INTERVAL_SECONDS - 1)
+    assert PRODUCT not in game.clicked
+
+
+def test_run_bot_buys_at_the_interval() -> None:
+    game = make_game()
+    run_bot(game, FakeClock(step=1.0), STORE_CHECK_INTERVAL_SECONDS + 2)
+    assert game.clicked.count(PRODUCT) == 1
+
+
+def test_run_bot_stops_buying_when_nothing_is_affordable() -> None:
+    game = make_game()
+    run_bot(game, FakeClock(step=1.0), STORE_CHECK_INTERVAL_SECONDS * 3)
+    assert game.clicked.count(PRODUCT) == 1
+
+
+def test_run_bot_stops_buying_when_a_purchase_fails() -> None:
+    game = make_game()
+    game.on_click = None
+    run_bot(game, FakeClock(step=1.0), STORE_CHECK_INTERVAL_SECONDS + 1)
+    assert game.clicked.count(PRODUCT) == 1
+
+
+@pytest.mark.parametrize("duration", [0, -1])
+def test_run_bot_rejects_a_non_positive_duration(duration: float) -> None:
+    game = FakeGame()
+    with pytest.raises(ValueError, match="positive"):
+        run_bot(game, FakeClock(), duration)
+    assert game.clicked == []
+
+
+def test_run_bot_propagates_an_unreadable_cps() -> None:
+    game = FakeGame(texts={CPS_ID: "nothing"})
+    with pytest.raises(UnreadableNumberError):
+        run_bot(game, FakeClock(), 1)
+
+
+def test_run_duration_default_is_the_constant() -> None:
+    clock = FakeClock(step=100.0)
+    game = FakeGame(texts={CPS_ID: "per second: 1"})
+    run_bot(game, clock)
+    assert clock.now == 100.0 * (RUN_DURATION_SECONDS // 100 + 1)

tests/unit/test_store.py

@@ -0,0 +1,100 @@
+"""@file
+@brief Tests of get_store_items, buy_upgrade and get_cps against a fake game.
+"""
+
+from decimal import Decimal
+
+import pytest
+
+from cookie_clicker_bot.application.use_cases.store import (
+    buy_upgrade,
+    get_cps,
+    get_store_items,
+)
+from cookie_clicker_bot.constants import (
+    CLASS_ATTRIBUTE,
+    COOKIE_COUNTER_ID,
+    CPS_ID,
+    PRODUCT_ID_PREFIX,
+    PRODUCT_PRICE_ID_PREFIX,
+)
+from cookie_clicker_bot.domain.errors import UnreadableNumberError
+from cookie_clicker_bot.domain.store_item import StoreItem
+from tests.unit.fakes import FakeGame
+
+
+def make_store(classes: dict[int, str], prices: dict[int, str]) -> FakeGame:
+    attributes = {
+        (f"{PRODUCT_ID_PREFIX}{i}", CLASS_ATTRIBUTE): c for i, c in classes.items()
+    }
+    texts = {f"{PRODUCT_PRICE_ID_PREFIX}{i}": p for i, p in prices.items()}
+    return FakeGame(texts=texts, attributes=attributes)
+
+
+def test_get_store_items_skips_locked_products() -> None:
+    game = make_store(
+        {0: "product unlocked enabled", 1: "product locked disabled", 2: "product"},
+        {0: "15", 1: "100", 2: "1,100"},
+    )
+    assert get_store_items(game) == [StoreItem(0, 15, True)]
+
+
+def test_get_store_items_reads_price_and_affordability() -> None:
+    game = make_store(
+        {
+            0: "product unlocked enabled",
+            1: "product unlocked disabled",
+            2: "product unlocked disabled",
+        },
+        {0: "15", 1: "1,100", 2: "1.5 million"},
+    )
+    assert get_store_items(game) == [
+        StoreItem(0, 15, True),
+        StoreItem(1, 1100, False),
+        StoreItem(2, 1_500_000, False),
+    ]
+
+
+def test_get_store_items_is_empty_when_nothing_is_unlocked() -> None:
+    assert get_store_items(FakeGame()) == []
+
+
+def test_get_store_items_propagates_an_unreadable_price() -> None:
+    game = make_store({0: "product unlocked"}, {0: "???"})
+    with pytest.raises(UnreadableNumberError):
+        get_store_items(game)
+
+
+def test_buy_upgrade_returns_true_when_the_cookies_drop() -> None:
+    game = FakeGame(texts={COOKIE_COUNTER_ID: "100 cookies"})
+
+    def spend(element_id: str) -> None:
+        game.texts[COOKIE_COUNTER_ID] = "85 cookies"
+
+    game.on_click = spend
+    assert buy_upgrade(game, StoreItem(3, 15, True)) is True
+    assert game.clicked == [f"{PRODUCT_ID_PREFIX}3"]
+
+
+def test_buy_upgrade_returns_false_when_the_cookies_do_not_drop() -> None:
+    game = FakeGame(texts={COOKIE_COUNTER_ID: "100 cookies"})
+    assert buy_upgrade(game, StoreItem(3, 15, True)) is False
+    assert game.clicked == [f"{PRODUCT_ID_PREFIX}3"]
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("per second: 0.1", Decimal("0.1")),
+        ("per second: 1,234.5", Decimal("1234.5")),
+        ("per second: 1.234 million", Decimal("1234000")),
+        ("per second: 0", Decimal(0)),
+    ],
+)
+def test_get_cps_reads_the_amount_after_the_colon(text: str, expected: Decimal) -> None:
+    assert get_cps(FakeGame(texts={CPS_ID: text})) == expected
+
+
+def test_get_cps_rejects_a_line_without_amount() -> None:
+    with pytest.raises(UnreadableNumberError):
+        get_cps(FakeGame(texts={CPS_ID: "per second"}))

tests/unit/test_store_item.py

@@ -0,0 +1,48 @@
+"""@file
+@brief Tests of the purchase strategy choose_upgrade.
+"""
+
+import dataclasses
+
+import pytest
+
+from cookie_clicker_bot.domain.store_item import StoreItem, choose_upgrade
+
+
+def test_choose_upgrade_picks_the_most_expensive_affordable_item() -> None:
+    items = [StoreItem(0, 15, True), StoreItem(1, 100, True), StoreItem(2, 1100, False)]
+    assert choose_upgrade(items) == StoreItem(1, 100, True)
+
+
+def test_choose_upgrade_returns_none_when_nothing_is_affordable() -> None:
+    assert choose_upgrade([StoreItem(0, 15, False), StoreItem(1, 100, False)]) is None
+
+
+def test_choose_upgrade_returns_none_for_an_empty_store() -> None:
+    assert choose_upgrade([]) is None
+
+
+def test_choose_upgrade_returns_the_only_item_when_it_is_affordable() -> None:
+    item = StoreItem(0, 15, True)
+    assert choose_upgrade([item]) == item
+
+
+def test_choose_upgrade_prefers_the_highest_index_on_equal_price() -> None:
+    items = [StoreItem(3, 50, True), StoreItem(7, 50, True), StoreItem(5, 50, True)]
+    assert choose_upgrade(items) == StoreItem(7, 50, True)
+
+
+def test_choose_upgrade_trusts_the_affordable_flag_at_price_boundary() -> None:
+    items = [StoreItem(0, 15, True), StoreItem(1, 16, False)]
+    assert choose_upgrade(items) == StoreItem(0, 15, True)
+
+
+def test_choose_upgrade_ignores_the_order_of_the_items() -> None:
+    items = [StoreItem(2, 500, True), StoreItem(0, 15, True), StoreItem(1, 100, True)]
+    assert choose_upgrade(items) == StoreItem(2, 500, True)
+
+
+def test_store_item_is_immutable() -> None:
+    item = StoreItem(0, 15, True)
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        item.price = 1  # type: ignore[misc]