Framework Architecture and Ownership

A new hire needs a helper that creates an order, so they add createOrder() to the nearest file that already imports requests — which happens to live under pages/. Six months later a driver migration touches forty files, import os appears inside page objects, and one utility module nobody owns is imported by everything. None of that is a coding-talent problem. It is an architecture with no boundaries, and boundaries start with a directory layout plus one import rule.

testfw/
├── config/      # env, capabilities, timeouts — the only layer reading process.env
├── core/        # browser factory, http client, retry policy, logging
├── pages/       # UI page objects: selectors + user actions
├── api/         # endpoint clients: routes + payloads, returns data
├── fixtures/    # builders, sessions, seeded data
├── tests/       # behavior only: arrange, act, assert
├── reporters/   # plugins and summaries
└── docs/adr/    # architecture decision records

The rule that gives the tree meaning: dependencies point one way — tests → pages/api/fixtures → core → config. Config imports nothing from the framework, tests are imported by nothing, and a violation fails review the same way a failing test fails CI. Each layer gets a one-line charter:

Enforcement that lives only in review survives as long as the reviewer's attention span, so the rule belongs in the linter:

// .eslintrc.json — an import that crosses a boundary fails CI
'no-restricted-paths': [
  'error',
  { target: './src/pages', from: './src/tests' },
  { target: './src/pages', from: './src/config' },
]

A boundary mistake now breaks the build exactly like a red test, and the charter stops being a document people argue about — it becomes the machine's answer to "why is my PR failing?".

When a page object needs a token, it does not go hunting: core builds the client from config and a fixture injects it, which is exactly the extension model from Fixtures, Plugins, and Extensibility applied at design time. The charter works because it answers the question reviewers actually ask — "is this file's knowledge allowed here?" — instead of debating style.

Missing boundaries announce themselves with symptoms you can scan for in an afternoon: circular imports (pages needing tests helpers), a config key change rippling through files in three directories, a selector string defined in two places, and helpers with five parameters because they serve five layers. Each symptom maps to a charter row that was never written down.

In an interview, "design a test framework" is usually a request to draw the layers and name what flows between them. Draw the tree, state the one-way rule, and then defend a boundary with a concrete consequence: selectors live in pages/ because a UI change should edit one directory; assertions live in tests because the API layer should serve both tests and seed scripts. The next problem is distributing the thing: one repository consumed by three teams needs versioning discipline.

Three teams each cloned the framework repository, patched their own bugs, and drifted for a year. A currency bug gets fixed twice in two repos and never in the third; a shared fixture behaves differently per team; and nobody can say which version production pipelines actually run. The fix is to stop treating the framework as a template and start treating it as a product with a version.

{
  "name": "@acme/test-framework",
  "version": "2.4.1",
  "private": true,
  "files": ["dist"],
  "peerDependencies": { "@playwright/test": "^1.48.0" },
  "scripts": { "build": "tsc -p tsconfig.build.json" }
}

The peerDependencies line deserves attention: the runner must exist exactly once in the dependency tree. Two installed copies of @playwright/test mean two test object identities — a custom fixture created by one copy is invisible to tests importing the other — plus a second download of browser binaries. Declaring the runner as a peer makes npm warn about duplicates instead of silently installing them.

Version discipline is what turns a package into a contract:

Release mechanics: changes land on main, the changelog is written with the PR, CI runs the framework's own suite against a sample consumer project, and pushing a tag (framework-v2.4.1) triggers npm publish --access restricted. Consumers declare a range — "@acme/test-framework": "^2.4.0" — so patch fixes arrive on the next npm ci without anyone editing tests, while a major is a deliberate act. For local work, npm link or a workspace reference points a product repo at your working copy; for risky changes, a prerelease channel (2.5.0-canary.7) lets one team validate before general availability. The release job itself is four lines of policy:

# .github/workflows/framework-release.yml — trigger: tag framework-v*
- run: npm ci && npm run build
- run: npm test && npm run test:consumer   # sample repo consuming the built tarball
- run: npm publish --access restricted     # publish only after both are green

On the consumer side, verify instead of assuming:

npm i -D @acme/test-framework@^2.4.0
npm ls @playwright/test    # exactly one copy, or the peer warning explains the duplicate

Which version, which runner, which config keys — the three support questions — get answered by the install itself.

The alternatives are worth stating plainly, because the trade-off decides your release train:

Interviewers follow with "how do you roll out a breaking change?" — answer in stages: deprecate in a minor with a @deprecated warning and a codemod where possible, ship the replacement alongside, cut the major with a migration section in the changelog, and support both for one cycle. Versioning only works if someone owns the repository itself, which is the last piece.

Frameworks do not usually collapse from bad design; they collapse from attrition. The person who built it changes teams, the publish token expires, two pull requests sit unreviewed for a month, and a product team forks the repo out of necessity. Ownership is the set of artifacts that keep decisions answerable when the original author is unreachable — and it fits in four files.

First, who approves what:

# .github/CODEOWNERS
/tests/framework/       @qa-sdet-team
/tests/framework/api/   @qa-sdet-team @payments-qa
/docs/adr/              @qa-sdet-team @tech-leads

Second, what "done" means for a framework pull request:

- [ ] New capability ships with an example under tests/examples/
- [ ] README tables updated (fixtures, matchers, reporters)
- [ ] semver bump chosen: patch / minor / major
- [ ] Breaking change carries a migration note and a deprecation in the prior minor
- [ ] Framework suite green, including the sample consumer project

Third, why a decision was made, recorded where the code cannot say it:

# ADR-0007: Playwright for new UI layers
Status: Accepted — 2026-02-19
Context: auto-waiting and trace viewer cut flake; team already knows locators;
         Selenium suites cover legacy flows and keep running.
Decision: new UI layers implement BrowserSession via Playwright adapter.
Consequences: two adapters coexist until the Selenium suite retires (target Q3);
              locator syntax differs across adapters — pages own that translation.

Fourth, the seam that makes a tool swap survivable — pages depend on a small stable interface, not on the vendor SDK:

interface BrowserSession {
  open(path: string): Promise<void>;
  text(selector: string): Promise<string>;
  screenshot(name: string): Promise<void>;
}
// adapters/playwright.ts and adapters/selenium.ts implement it;
// core wires the adapter from config — pages never import the vendor package

A migration then edits adapters and core/, while two hundred page methods and a thousand tests stay untouched. The same seam protects upgrades in the other direction: a Playwright minor release with a changed fixture API lands in one module.

Ownership is also operational. Deprecations get teeth with a policy — @deprecated use waitForOrder(); removed in 3.0 — announced in a minor, enforced in the next major, never deleted silently. The warning has a standard form, and it surfaces in editor hints and lint output so consumers get a full minor cycle to migrate before the major removes anything:

/** @deprecated use waitForOrder() — removal scheduled for 3.0 */
waitForLegacySpinner(timeout = 5000) { ... }

A removal nobody saw coming is how trust in a shared package dies; a removal predicted for a whole release cycle is just maintenance. Releases need a rotation rather than a single holder of the npm token: a documented publish flow, two people who have run it, and a monthly dependency bump so the upgrade surface never becomes a cliff. Three numbers show whether the architecture is holding: how many product teams consume the published package, how long a new hire takes to first green (target under a day), and the framework's flake rate trend. Those numbers need a calendar behind them: a monthly dependency-bump pull request, a rotating framework on-call who triages suite failures instead of letting them pile up in a channel, and a quarterly pass over the ADRs marking superseded decisions rather than deleting them. Onboarding is the real test of the whole system — a new engineer should go from clone to a merged framework pull request in a day using nothing but CODEOWNERS, the checklist, and the README.

Say all of that in an interview as a system: layers with a one-way rule, a package with semver discipline, and ownership artifacts (CODEOWNERS, ADRs, deprecation policy) that outlive any individual. That system is exactly what you assemble piece by piece in Designing the Capstone Framework, and the extension points it protects came from Fixtures, Plugins, and Extensibility.