Extending The System

Key	Value
Status	Active
Owner	QA Automation
Updated	2026-03-26
Scope	How to add sites, suites, handlers, integrations, and publishable documentation safely

Extending PW-Tests is less about adding more code and more about putting new behavior in the right place. The repo is easier to maintain when site-specific logic stays in config, suite-specific behavior stays near the suite, and operational behavior stays in scripts and services instead of leaking into every test.

The Right Way To Add Something New

You Want To Add	Start With
new site	shared site config and selectors
new test suite	suite file plus CI wiring and docs
new content surface	content registry and the right handler
new failure intelligence	service layer and data files
new integration	`src/integrations/` or `scripts/` plus docs
new Confluence page	`docs/wiki/` or `docs/confluence/` plus publishing flow

Adding A New Site

Step	What To Do
1	add the site configuration and base selectors
2	define consent behavior correctly
3	add or verify mobile surfaces if mobile matters
4	run smoke first, then PDT and one deeper suite
5	update docs so operators know the site’s quirks

Important rule: do not bury one site’s exception inside generic helpers if it is truly site-specific.

Adding A New Test Suite

Before adding a suite, answer this first: what decision will this suite help someone make?

Good reasons:

it covers a risk area the current suites miss
it gives a cheaper signal than a deeper suite
it protects revenue, compliance, or editorial production

Weak reasons:

it duplicates existing coverage with a new name
it exists only because one test did not fit neatly somewhere else

Adding To The Content System

Content work has its own structure. New module coverage usually belongs in the content registry and handler system, not as one-off logic in unrelated suites.

If You Need To Add...	Usually Update...
a new module type	content registry plus handler support
a better seed URL	registry entry or site seed source
a new interaction depth	content tests tiering and handler logic

Adding Failure Intelligence

If you are extending incident understanding, keep the layers separate.

Layer	Good Extension Example
symptom parsing	detect a new technical failure shape
incident memory	add a resolved recurring incident
priors	improve weighting from recoveries
Slack verdict logic	improve how confidence is described to humans

Adding An Integration

A good integration has three parts:

clear config and credentials
a narrow code boundary
docs that explain who uses it and why

That keeps the repo from turning into a pile of hidden environment assumptions.

Extending Confluence Documentation

Confluence-source docs are first-class project assets here. If you add a feature, update the docs in the same change.

Rule	Why It Matters
write for humans, not just for grep	these pages are operator documentation
avoid heavy code blocks	Confluence pages should stay readable
prefer tables and expand sections	better scanning in Confluence
keep the published source in git	docs should be reviewable like code

Good Extension Checklist

Check	Why It Protects The Repo
config lives in the right layer	avoids hidden coupling
commands are documented	operators can actually use the feature
CI job has a clear purpose	avoids schedule bloat
Slack behavior is intentional	prevents noisy or misleading alerts
docs are updated	avoids drift between repo and Confluence

define the problem clearly
choose the right layer for the change
implement the smallest version that proves the value
wire CI and reporting only if the signal is worth it
update docs and publishable Confluence source in the same pass

Need	Go To
system layout	Architecture Overview
suite purpose	Test Types
config and env vars	Configuration Guide
Confluence rules	`.confluence/WRITING_RULES.md` in the repo