Test Automation Framework Architecture and Code Organization Questions

Direct answer. Page Object Model wraps each page in a class of locators-plus-actions; the Screenplay pattern instead models a user (an "Actor") who performs Tasks and asks Questions, with no single class owning "the page" - for a straightforward flow like checkout, POM is usually the better choice, and Screenplay earns its complexity only once the app has many actors/roles or many cross-cutting interaction styles.

Structured elaboration.

• Core concepts: POM = one class per page/component, holding locators and action methods. Screenplay = Actors that use Abilities (e.g. "browse the web"), perform Tasks (e.g. "add an item to the cart," itself composed of smaller Tasks/Interactions), and ask Questions (e.g. "what is the cart total") - the page structure becomes an implementation detail behind Interactions, not the organizing unit.
• Typical responsibilities: in POM, a CheckoutPage class owns everything about that page. In Screenplay, the checkout FLOW is a Task any Actor can perform, decoupled from which page(s) it touches - a Task can span multiple pages without any one "page class" growing to know about all of them.
• Readability, reusability, onboarding: POM is quicker to learn (most engineers have seen a class-per-page structure before) and reads fine for simple flows. Screenplay reads more like natural language for MULTI-STEP flows ("Alice attempts to checkout with an expired card") but has a steeper learning curve for new contributors, since the Actor/Task/Question vocabulary is unfamiliar until they've seen a few examples.

Worked example. A complex multi-step checkout (add to cart -> apply promo -> select shipping -> pay) spanning four pages: in POM, either one CheckoutFlowPage class grows to know about all four pages' locators (a "god object"), or four page classes get orchestrated ad hoc by the test itself. In Screenplay, Actor.attemptsTo(AddItemToCart.of(item), ApplyPromoCode.of(code), SelectShipping.express(), PayWith.card(card)) reads as the business flow, and each Task internally handles which page it needs without leaking that detail to the test.

Trade-offs and pitfalls. Screenplay's benefit is proportional to how many DISTINCT actors/roles and how tangled the multi-page flows are; for a single-actor, mostly-single-page-per-flow app, it adds ceremony (Abilities, Tasks, Questions, Interactions as separate classes) without a payoff, and a team that adopts it prematurely spends more time writing scaffolding than tests. The senior call is choosing based on the app's actual shape, not on which pattern reads as more sophisticated.

Direct answer. A reusable ProductCard component object is built once, taking a ROOT SELECTOR as a constructor parameter so any page can instantiate as many independent instances as it has matching elements - the component's methods (get_price, click_add_to_cart) always operate scoped to their own root, so two cards on the same page never interfere with each other, and any OTHER page (catalog, search results, wishlist) reuses the identical class with zero duplication.

Structured elaboration. The key design decision is that ProductCard takes its root selector at construction time and every action/query it exposes is scoped WITHIN that root (find_within(root, sub_selector)), never querying the whole page - this is what makes multiple instances on one page safe, and what makes the SAME class portable to a completely different page. A composing page (CatalogPage, WishlistPage) is responsible only for discovering how many card roots exist and instantiating one ProductCard per root; it has no opinion about what a card does internally.

Worked example. Executed (Python, a fake DOM/driver including the find_within scoping and the composing pages that actually produce the run output below):

class FakeElement:
    def __init__(self, text=None):
        self.text = text
        self.clicked = False
    def click(self):
        self.clicked = True

class FakeDriver:
    """Fake DOM: maps (root_selector, sub_selector) -> element, so
    find_within can be scoped and cards don't share state."""
    def __init__(self):
        self.elements = {}
    def register(self, root, sub, element):
        self.elements[(root, sub)] = element
    def find_within(self, root, sub_selector):
        return self.elements[(root, sub_selector)]

class ProductCard:
    def __init__(self, driver, root_selector):
        self.driver, self.root = driver, root_selector
    def get_price(self):
        return self.driver.find_within(self.root, "price").text
    def click_add_to_cart(self):
        self.driver.find_within(self.root, "add_to_cart").click()

class CatalogPage:
    def __init__(self, driver, card_roots):
        self.cards = [ProductCard(driver, root) for root in card_roots]

class WishlistPage:
    def __init__(self, driver, card_roots):
        self.cards = [ProductCard(driver, root) for root in card_roots]

driver = FakeDriver()
driver.register("card-1", "price", FakeElement(text="$19.99"))
driver.register("card-1", "add_to_cart", FakeElement())
driver.register("card-2", "price", FakeElement(text="$9.99"))
driver.register("card-2", "add_to_cart", FakeElement())

catalog = CatalogPage(driver, ["card-1", "card-2"])
catalog.cards[0].click_add_to_cart()
print(f"CatalogPage: card 1 price = {catalog.cards[0].get_price()} | add-to-cart clicked = {driver.find_within('card-1','add_to_cart').clicked}")
print(f"CatalogPage: card 2 add-to-cart clicked (should be False) = {driver.find_within('card-2','add_to_cart').clicked}")

wishlist_driver = FakeDriver()
wishlist_driver.register("wl-card-2", "price", FakeElement(text="$9.99"))
wishlist_driver.register("wl-card-2", "add_to_cart", FakeElement())
wishlist = WishlistPage(wishlist_driver, ["wl-card-2"])
wishlist.cards[0].click_add_to_cart()
print(f"WishlistPage reused the identical ProductCard class: card 2 add-to-cart clicked = {wishlist_driver.find_within('wl-card-2','add_to_cart').clicked}")

Actual run output, with two cards on a CatalogPage:

CatalogPage: card 1 price = $19.99 | add-to-cart clicked = True
CatalogPage: card 2 add-to-cart clicked (should be False) = False
WishlistPage reused the identical ProductCard class: card 2 add-to-cart clicked = True

Clicking card 1's add-to-cart left card 2 completely untouched (per-instance scoping confirmed, not a shared singleton), and instantiating the SAME ProductCard class on a totally different page (WishlistPage) worked identically with zero code changes - both assertions the design is meant to guarantee.

Trade-offs and pitfalls. A component object's root-scoping only helps if EVERY method genuinely queries within the root; a single method that accidentally queries the whole page (a copy-pasted selector missing the root-scoping call) silently reintroduces cross-instance interference that will only surface as a flaky test on a page with multiple card instances, not on a page with just one.

Direct answer. Test code deserves the same code-quality discipline as production code, applied through the same mechanisms: linting and static analysis catch mechanical issues automatically, unit tests for shared helper utilities catch logic bugs in the framework itself, a consistent style and branching/PR policy keep the codebase navigable across contributors, and a review checklist focused specifically on DETERMINISM and MAINTAINABILITY (not just "does it pass") catches the issues generic code review misses.

Structured elaboration.

• Linting: catches mechanical anti-patterns automatically (bare sleep() calls, unused imports, overly broad exception catches) before a human reviewer needs to notice them by eye.
• Static analysis: type-checking (mypy, TypeScript's compiler) catches an entire class of bugs (a renamed field, a wrong argument type) at commit time rather than as a runtime failure deep in a test run.
• Unit tests for helper utilities: the FRAMEWORK'S OWN shared code (a retry helper, a custom assertion, a data-generation utility) needs its own tests - a bug in shared framework code silently corrupts every test that depends on it, often without anyone noticing until a real production bug slips through a test that "passed" using a broken helper.
• Consistent style: enforced via an auto-formatter (black, prettier), removing style bikeshedding from code review entirely so reviewers focus on substance.
• Branching and PR policies: a required review before merge, CI green as a merge gate, and a policy that a newly-introduced flaky test blocks the PR that introduced it rather than becoming the next person's problem.
• Review checklist focused on determinism and maintainability: does this test rely on real time/sleep anywhere? Does it depend on execution order or shared mutable state? Is any locator/assertion duplicated elsewhere that should be centralized? Would a failure of this test tell a future reader clearly what broke?

Worked example. A concrete review-checklist item catching a real issue: a reviewer applying "does this rely on real time?" to a new test notices time.sleep(3) before an assertion - flagged and replaced with an explicit wait before merge, catching exactly the anti-pattern that linting alone might miss if the specific sleep() call pattern isn't yet covered by an automated rule.

Trade-offs and pitfalls. Linting and static analysis catch what's MECHANICALLY detectable; determinism and maintainability issues (a test that happens to pass only because of execution order, a locator that's technically valid but brittle) usually require a human reviewer applying a checklist deliberately - treating automated tooling as sufficient on its own, without the human-checklist layer, misses exactly the subtler issues that cause real flakiness months later.

Direct answer. A framework for a large microservices ecosystem needs a REPOSITORY-LAYOUT decision (mono-repo vs one-repo-per-service) made deliberately against your team topology, a way to share and version fixtures/libraries across dozens of independently-deployed services, a parallel-execution strategy that scales with service count, and END-TO-END TRACEABILITY so a failing test points back to the owning service and the exact commit that broke it.

Structured elaboration.

• Repository layout: mono-repo favors CONSISTENT tooling/versions and atomic cross-service changes but requires strong CI-scoping (so a change to one service doesn't trigger every other service's test suite); per-service repos favor team autonomy and independent release cadence but require deliberate work to keep shared fixtures/libraries from drifting between services. The right choice tracks your ORG'S deploy model: if services deploy independently on their own schedule, per-service repos (with a shared library published/versioned like any dependency) usually fit better; if the org deploys in lockstep, mono-repo's atomicity is worth more.
• Sharing/versioning common fixtures and libraries: published as versioned packages (semantic versioning, a compatibility test suite, a documented deprecation window before removal), consumed as an explicit dependency by each service's test suite, never copy-pasted between service repos.
• Reliable parallel execution at scale: sharding tests by SERVICE BOUNDARY first (each service's suite is independently parallelizable), then within a service by test file/class, so the sharding strategy scales roughly linearly as services are added rather than requiring a global re-balance every time.
• Traceability from a failing test to owning service and commit: every test result is tagged with the service it exercises AND the commit SHA of that service's code at test time, so a CI failure surfaces "checkout-service, commit abc123" rather than a bare test name a triager has to manually trace back through several systems.

Worked example. A concrete traceability implementation: the test result schema includes {"service": "checkout-service", "service_commit_sha": "abc123", "test_name": "..."}, populated by the CI job that triggered the test run (which already knows which service's deploy triggered it); a failure dashboard groups by service first, so an on-call engineer for checkout-service sees exactly their own failures without wading through the other 199 services' results.

Trade-offs and pitfalls. Sharding purely by test COUNT (ignoring service boundaries) balances CI worker load evenly but destroys the traceability benefit, since a shard can straddle multiple services and a failure's "owning service" becomes ambiguous; sharding by service boundary first costs some load-balancing efficiency (services vary in test-suite size) but keeps every failure attributable, which matters more at genuine scale than shaving a few minutes off the slowest shard.

Direct answer. In a mono-repo spanning frontend, backend services, and shared libraries, test organization needs a directory/naming layout that makes ownership and speed-tier obvious at a glance, and CI needs intelligent TEST SELECTION so a change to one service doesn't trigger every other service's suite - the difference between "runs fast" and "runs everything, slowly" at mono-repo scale is almost entirely about selection, not about individual test speed.

Structured elaboration.

• Directory layout and naming: each top-level component (frontend/, services/checkout/, services/inventory/, libs/shared-utils/) owns its own tests/ directory internally, with a consistent naming convention (test_* / *.test.ts) so a global test-discovery tool can find everything without per-component configuration.
• Fast vs slow suites, tags/annotations: every test is tagged both by SPEED (fast/slow) and by OWNING COMPONENT (checkout, frontend), so CI can compose exactly the right subset for a given change.
• CI stage integration: a PR pipeline stage that determines "which components changed" (via a diff against the merge-base) and runs only THOSE components' fast test suites, deferring slow/cross-component suites to a merge-to-main or nightly gate.
• Test selection for PRs, avoiding unnecessary suites while maintaining safety: the selection logic needs to account for shared-library changes specially - a change to libs/shared-utils potentially affects every consumer, so the selection algorithm must trigger the fast suites of ALL components depending on that library, not just the library's own tests, while a change scoped entirely to services/checkout/ triggers only checkout's (and anything that directly imports from checkout, if such cross-service imports exist).

Worked example. A concrete selection rule: build a dependency graph at repo-analysis time (which components import from which shared libraries); on a PR, diff the changed files against that graph to compute the "affected component set"; run each affected component's fast-tagged tests in the PR gate, and run the FULL affected set's slow-tagged tests only if the PR touches a shared library used by many components (where the blast radius of a bug is large enough to justify the extra CI time even on the PR itself).

Trade-offs and pitfalls. A test-selection algorithm that's too conservative (running everything "just to be safe" whenever a shared library changes) defeats the entire point of selective execution and becomes a mono-repo antipattern in its own right; one that's too aggressive (narrowly scoping to only the literally-changed files, missing transitive dependents) creates a real risk of shipping a breaking shared-library change that no PR gate ever caught - the dependency graph needs to be genuinely accurate and kept up to date as the codebase evolves, or the selection logic becomes a false sense of safety.