Framework Documentation and Onboarding

The engineer who built the framework knows every implicit decision: why DriverManager uses ThreadLocal instead of a static field, why page objects return the next page object on navigation methods, why the config reads environment variables before properties files. That knowledge exists exactly once, in one person's head. When they leave — or take a holiday — new engineers spend days discovering what should take an hour. Framework documentation is not a nice extra. It's the mechanism that makes a framework an institutional asset rather than a single person's speciality. This lesson covers the four documents every framework needs and the onboarding process that gets a new engineer writing their first test on day one.

The four documents

1. README — the entry point

The README is the first thing a new engineer reads. It must answer four questions without requiring them to ask anyone:

What is this? One paragraph describing the framework, the tool stack, and what it tests. No history, no preamble.

How do I run it? The exact commands to install dependencies and run the suite on a fresh checkout. Not "you'll need Java and Maven" — the specific version, the specific commands:

## Prerequisites
- Java 21+ (`java -version`)
- Maven 3.9+ (`mvn -version`)
- Chrome (latest stable)
 
## Run the suite locally
\```bash
git clone git@github.com:yourorg/your-framework.git
cd your-framework
cp .env.example .env        # fill in ADMIN_PASSWORD and API_KEY
mvn test -Denv=staging
\```
 
## Run smoke tests only
\```bash
mvn test -Denv=staging -Dgroups=smoke
\```

Where is everything? A 10-line folder structure guide:

## Project structure
src/test/java/
├── base/         BaseTest, BasePage — framework foundation
├── pages/        Page objects, one class per page
├── tests/        Test classes, mirroring app feature areas
├── data/         UserFactory, ProductFactory, DataReader
├── config/       Config.java — single entry point for all config
├── utils/        DateHelper, ScreenshotHelper, WaitHelper
└── listeners/    ExtentReportListener, ArtifactListener

How do I add a test? A link to the tutorial (document 3) or a 5-line inline guide.

2. CONTRIBUTING — the conventions

CONTRIBUTING answers: "I know the project; how does this team work?"

## Conventions
 
**Naming**
- Test classes: `FeatureNameTest.java` (e.g., `CheckoutTest`, `LoginTest`)
- Test methods: `actorCanDoSomething` (e.g., `adminCanPublishPost`)
- Page objects: `PageNamePage.java` (e.g., `LoginPage`, `CheckoutPage`)
 
**Branching**
- Feature branches: `feature/short-description`
- Bugfix branches: `fix/what-was-broken`
- PR into `main`; squash merge
 
**Test data**
- Always use factories: `UserFactory.randomUser()`, not hardcoded emails
- Always clean up in `@AfterMethod(alwaysRun = true)`
 
**Waits**
- Never use `Thread.sleep()`
- Always use `ExpectedConditions` or `WebDriverWait`
- Timeouts read from `Config.timeoutSeconds()`
 
**PR checklist**
Copy the test automation review checklist from `.github/pull_request_template.md` and fill it in.

3. Tutorials — hands-on guides

Two tutorials cover 90% of what a new engineer needs to know:

"Add your first test" (30-minute tutorial): Step-by-step guide that walks through creating a page object, writing a test, running it, and seeing it pass. Uses a real feature from the application. By the end, the engineer has committed working code. This is worth more than any amount of architecture documentation.

"Debug a failing test" (20-minute tutorial): Walks through the debugging workflow: read the report screenshot, enable DEBUG logging, use the Playwright trace viewer or remote Chrome DevTools, identify the failing step. This is the skill that turns a frustrating afternoon into a 30-minute investigation.

Both tutorials belong in the docs/ folder, written in Markdown, version-controlled, and updated whenever the process they describe changes.

4. Architecture Decision Records

ADRs are the most underused documentation type. They capture not what was decided but why — the context, the options considered, and the reason one option was chosen over the others.

# ADR-001: ThreadLocal for WebDriver management
 
**Date:** 2025-08-12
**Status:** Accepted
 
**Context**
We need parallel test execution to keep the CI runtime under 30 minutes as the suite grows. WebDriver is not thread-safe.
 
**Options considered**
1. Sequential execution only — safe but too slow
2. Static WebDriver field — fast but produces race conditions in parallel
3. ThreadLocal<WebDriver> — each thread gets its own driver instance
 
**Decision**
ThreadLocal<WebDriver> in DriverManager. Teardown calls driver.remove() to prevent memory leaks.
 
**Consequences**
Page objects must receive the driver via constructor (DriverManager.getDriver()), not via a static field. @AfterMethod must have alwaysRun=true to guarantee driver cleanup.

An ADR for each non-obvious decision prevents engineers from "fixing" the ThreadLocal pattern back to a static field because it "looked simpler." The record explains why the simpler-looking option was rejected.

The onboarding process

Documentation without an onboarding process produces engineers who read docs once and then work from memory (which may be incomplete). A structured first week ensures the documentation is exercised and gaps are caught:

Day 1 — environment: Clone the repository. Follow the README exactly. Run the full suite. If anything fails, the README has a gap — fix it before the next engineer onboards.

Day 2 — orientation: Read the CONTRIBUTING guide. Read 5 existing test files and 5 page objects. Identify the patterns from Chapters 1–4 of this course. Ask one question about anything that isn't clear.

Day 3 — first test: Follow the "Add your first test" tutorial. Write a test for a simple feature. Submit a PR. The PR review provides personalised feedback on framework conventions.

Week 1 end — own 3 tests: The engineer has 3 tests merged to the main branch. They understand the factory pattern, the page object structure, the config system, and the review process.

Week 2 — review someone else: The engineer reviews a test PR from a teammate. Applying the checklist from the other side reinforces the conventions and spreads review skills.

Living documentation

Documentation that's written once and never updated is worse than no documentation — it actively misleads. The solution is to make docs part of the PR process:

• If a PR changes how tests are run → update the README
• If a PR changes a convention → update CONTRIBUTING
• If a PR makes a non-obvious architectural decision → create an ADR
• If a PR adds a new tool or pattern → update or add a tutorial

"Documentation updated" belongs in the PR checklist alongside "tests pass." Treat a PR that changes behaviour without updating docs as incomplete.

⚠️ Common mistakes

• A 30-page architecture document that nobody reads. Length is the enemy of adoption. Engineers read READMEs if they're short, tutorials if they're practical, and ADRs if they're specific. Write less, link more. A 2-page README that links to specific tutorials is more useful than a 30-page wiki.
• Documentation that describes aspirations, not reality. A README that says "all tests use data-testid selectors" when 30% of them use XPath is worse than no documentation — it creates confusion when engineers discover the discrepancy. Document what the framework is, not what you wish it were.
• Onboarding as a one-time event. A new engineer's onboarding week reveals documentation gaps that experienced engineers no longer notice. After each onboarding, the new engineer should update the docs to reflect what was unclear or missing. This keeps documentation calibrated to the actual beginner experience.

🎯 Practice task

Write the essential documentation for your framework — 45 minutes.

1. README audit. Open your project's README (create one if it doesn't exist). Apply this test: hand it to a colleague who has never seen the project. Can they clone, install, and run one test in 15 minutes? If not, fix the gaps you observe.
2. Write the folder structure guide. Describe each top-level directory in your test project in one sentence. This is the single most useful orientation for a new engineer.
3. Write one ADR. Pick the most non-obvious decision in your framework (ThreadLocal driver, the reason you chose TestNG over JUnit, why you use ExtentReports over Allure). Write the ADR template: context, options considered, decision, consequences. Save as docs/adr/001-decision-name.md.
4. Write the "add your first test" tutorial. Create docs/tutorials/add-your-first-test.md. Walk through: (a) creating a page object for one page, (b) writing a test that uses it, (c) running it locally, (d) submitting a PR. Every step should include the exact command or code snippet.
5. Stretch — run the onboarding process. Ask a colleague (or use yourself as a "beginner") to follow the docs from scratch on a clean machine. Time how long it takes to get the first test running. Everything that requires asking a question is a documentation gap. Fix those gaps. Repeat until the first test runs in under 30 minutes from a clean checkout.

This chapter — and the course — ends here. You've covered the full lifecycle of a production test automation framework: foundational patterns, architecture principles, design patterns, framework components, cross-cutting concerns, and the maintenance practices that keep a framework valuable as the team and application grow.