A QA automation framework is a structured set of guidelines, coding standards, tools, and reusable components that enables consistent, maintainable, and scalable automated test execution across a software product's lifecycle.
Most teams build their first framework under time pressure. They end up with a folder of test scripts that work today but collapse when the product grows, the team changes, or the CI/CD pipeline gets more demanding. This guide covers the architecture decisions that prevent that collapse.
Why most automation frameworks fail
- Built for speed, not maintainability. Copy-pasted locators, hardcoded test data, and no abstraction layer. Works for 50 tests. Breaks at 500.
- No ownership model. If everyone maintains the framework, no one maintains the framework. Flaky tests accumulate. Trust in the suite erodes.
- Brittle locator strategy. XPath expressions tied to DOM position break every time the frontend is refactored. CSS selectors tied to generated class names break at every build.
The four-layer architecture that scales
The Assurix framework is built on four distinct layers. Each has a clear purpose and a clear owner.
- Layer 1 — Test Layer. Test classes, test suites, and data providers. QA engineers write test cases here. Test methods call Page Objects — they do not interact with the browser directly.
- Layer 2 — Page Object Layer. Every page or major component has a corresponding Java class holding element locators and user action methods.
LoginPage.javacontains the username field, password field, and alogin()method. Nothing else. - Layer 3 — Utility Layer. Shared helpers:
WaitUtils(explicit waits),ExcelReader(test data),ExtentManager(report initialisation),ScreenshotUtils(failure capture). No test logic — only utility functions. - Layer 4 — Configuration Layer.
config.propertiesfor environment URLs and credentials,testng.xmlfor suite and parallel execution,pom.xmlfor dependencies. Environment-specific configs are separate files, never hardcoded values.
Tool selection: what Assurix uses and why
- Language: Java — stable, enterprise-supported, extensive Selenium community
- Browser automation: Selenium WebDriver — mature, supports all browsers, CI-friendly
- Build and dependency management: Apache Maven — standardised, integrates with all CI tools
- Test runner: TestNG — parallel execution, grouping, data providers
- Reporting: ExtentReports + Allure — rich HTML reports, timeline view, failure screenshots
- Containerisation: Docker — consistent execution environment across local and CI
- CI/CD: Jenkins / GitHub Actions — pipeline triggers, test result publication
Keeping the framework healthy long-term
Flaky test detection and quarantine. A test that fails intermittently is worse than no test — it trains the team to ignore red builds. Tag flaky tests, quarantine them from the main gate, investigate root cause, and fix or delete. Never accept persistent flakiness.
Quarterly framework audits. Every quarter, review locator strategies, check for test duplication, update dependencies, and validate that the suite still covers the product's most critical paths. The framework is a product — it needs maintenance.
Parallel execution from day one. Configure TestNG for parallel test execution early, before the suite grows large. Retrofitting parallelism into an existing suite is significantly harder than building for it from the start.
Real outcome
Using this architecture, Assurix took a B2B SaaS analytics startup from zero automation to 75% regression coverage in 8 weeks. The team went from manual regression taking 3 days per release to a 45-minute automated suite running on every merge. Support tickets related to regression-introduced bugs dropped 40% within the first quarter.
Frequently Asked Questions
Should we build our own framework or use an open-source one?
Build your own on top of established libraries (Selenium, TestNG, Maven). Off-the-shelf frameworks (Cucumber, Karate) add abstraction that slows debugging. A custom framework using established primitives gives you full control and faster maintenance.
How many automated tests is "enough" for a SaaS product?
Coverage percentage is less important than coverage of the right paths. Prioritise: 100% of happy-path critical user journeys, 100% of payment and authentication flows, 80%+ of regression-prone features. The risk profile matters more than the count.
What is the Page Object Model?
The Page Object Model (POM) is a design pattern where each UI page has a corresponding class in the test codebase. The class holds element locators and user action methods. Tests call these methods rather than interacting with the browser directly. When a UI element changes, you update one class — not every test that uses it.
Need a framework built and owned for your team? See how Assurix handles automation for SaaS and fintech products.