Lesson 81: Architecture Planning

Module 9 — The Master Capstone | Unified Quality Assurance Platform (UQAP)

Goal: Draw the blueprint of our final framework — directory structure, library choices, and CI/CD flow — before writing a single line of test code.

---

The Junior Trap: “I’ll Just Put Everything in One Folder”

Imagine you just learned Selenium. You’re excited. You write your first test:

project/
├── test_login.py
├── test_checkout.py
├── test_search.py
└── helpers.py

This works. Until it doesn’t.

Here is what happens when this “flat folder” project grows to 50 tests and gets pushed into a CI/CD pipeline:

• A teammate edits helpers.py to fix login — and silently breaks the checkout test.

• Two tests try to write to the same results.html file simultaneously during a parallel run. One corrupts the other.

• The CI machine doesn’t have Chrome in the same path as your laptop. Everything fails with a cryptic WebDriverException.

• A new library version ships. Nothing is pinned. The pipeline that worked on Monday breaks on Tuesday with a ModuleNotFoundError you didn’t ask for.

None of these bugs are “test bugs.” They are architecture bugs. And architecture bugs are invisible until your pipeline is on fire at 2 AM.

---

The Failure Mode: Death by Coupling

The root cause is tight coupling: when every piece of code knows too much about every other piece of code.

In the flat folder above:

• test_login.py directly calls helpers.py, which directly calls selenium.webdriver, which directly assumes a local Chrome binary.

• Change one thing → everything downstream breaks.

This is called a fragile test suite. The technical term is high afferent coupling. In plain English: pull one thread and the whole sweater unravels.

The specific symptoms you will see in CI:

Symptom Root Cause FileNotFoundError on driver path No driver abstraction layer Tests pass locally, fail in CI Hardcoded file paths, no pathlib Random failures on parallel runs Shared mutable state across tests One lib update kills everything No dependency pinning / no requirements.txt layering

---