Tags: #testing #kotlin #opensource #cicd

Many test automation frameworks don't meet the engineering standards they're supposed to uphold.

I say that having used several professionally. Slow execution, brittle locators, silent failures, opaque logic, dead code, documentation that contradicts itself, CI pipelines held together with workarounds, and — my personal favourite — a framework from a reputable company whose generated selectors were so long they wouldn't fit on a widescreen. Its tooling produced 95% noise. Core functions silently failed or behaved unpredictably.

The cruel irony: frameworks built to enforce quality, failing their own quality bar.

So I built my own. This is QED.

What QED is

QED is a Kotlin DSL test automation framework for UI and API testing — open source, MIT licensed, and built from scratch on SOLID principles. The name comes from Quod Erat Demonstrandum — "that which was to be proven." Every test is a proof. Every run is evidence.

The framework takes that idea into the reporting layer:

• ✅ Passed — Quod erat demonstrandum. Proven.
• ⚠️ Skipped — Quaestio manet. The question remains.
• ❌ Failed — Investigandum est. Further investigation is required.

It's built on top of tools you probably already know — Playwright, REST-assured, TestNG, and ExtentReports — but wraps them in expressive Kotlin DSLs that make tests read like intent rather than implementation.

The problems it solves

Brittle page objects

Most frameworks treat page objects as monoliths — tightly coupled, hard to reuse, duplicated across the suite. QED uses screen area composition: pages are assembled from smaller, independently testable components (header, sidebar, modal, etc.). If a shared component changes, you fix it once.

Glue code hell

Tools like Cucumber promise readable tests but often deliver fragmented logic split across step definitions, regex matchers, and external feature files. QED's DSL keeps the test logic in one place, expressed in the language of the domain.

Opaque CI pipelines

GitHub Actions configs have a way of growing into spaghetti. QED ships with a clean, documented pipeline structure — separate frontend and backend jobs, proper caching, and no redundant steps.

What the DSL looks like

Here's a mixed UI + API test — both in the same test context, sharing setup:

private val baseTest = BaseTest()
private val hasRest = HasRest(baseTest, urlKey = "apichallenges")
private val hasBrowser = HasBrowser(baseTest, urlKey = "uitestingurl")

class UI_RESTTest : TestContext(baseTest, hasBrowser, hasRest) {

    @Test(priority = 0, description = "mixed UI/API test", groups = ["All"])
    fun testUI_Rest() {
        val payroll = Payroll("create todo process payroll", true, "todo description")
        val json = QEDJson.toJson(payroll)
        val landingPage = GenericPage(UITestingPage(this))

        hasBrowser?.apply {
            navigateToApp()
            startFromPage(landingPage) {
                val result = rest.send(RequestType.POST, APIChalURLPath.SIM_ENTITIES, json, 201)
                verify("check response body") {
                    expect(result.get("name").asText()).to.equal("bob")
                    expect(result.get("id").asInt()).to.equal(11)
                }
            }
        }
    }
}

The test reads top to bottom. There's no ceremony. The verify block is expressive enough that a non-engineer could follow the intent, but precise enough that an engineer can debug a failure without spelunking.

Real-world use: DairyMax

QED isn't a demo project. I use it to test DairyMax, a production web application I'm building. The framework runs in a GitHub Actions pipeline on every push — UI tests in one job, API tests in another, with proper dependency management between them.

That's meant one very practical constraint shaped the entire design: the framework has to work cleanly in CI, not just locally. Playwright browser setup, environment-specific SUT profiles, and test tagging (groups = ["All"], groups = ["Smoke"]) all came out of that real-world friction.

Architecture overview

qed-framework/
├── src/                   # Core framework
│   ├── base/              # BaseTest, TestContext
│   ├── browser/           # HasBrowser, Playwright wrappers
│   ├── rest/              # HasRest, REST-assured wrappers
│   ├── dsl/               # Verify, expect, page DSL
│   └── reporting/         # ExtentReports integration
├── QED-Shared/            # Shared utilities (submodule)
├── qed-demos/             # Example tests
└── .github/workflows/     # CI/CD pipelines

The HasBrowser and HasRest capabilities are composed into a TestContext — you only include what a given test class needs. A pure API test never touches Playwright. A UI test that doesn't need REST doesn't carry that weight.

CI/CD with GitHub Actions

The pipeline is split into two jobs:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
      - name: Run API tests
        run: ./gradlew test -Dgroups=API

  ui-tests:
    runs-on: ubuntu-latest
    needs: api-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
      - name: Install Playwright browsers
        run: ./gradlew installPlaywright
      - name: Run UI tests
        run: ./gradlew test -Dgroups=UI

UI tests run after API tests pass. Playwright browsers are installed as a dedicated step. Reports are archived as artifacts. Nothing clever, nothing fragile.

What's next

QED is intentionally lean. I want to keep it that way — the modular architecture makes it straightforward to extend without bloating the core. On the roadmap: deeper SUT profile management, richer assertion matchers, and longer term, some interesting ideas around AI-assisted test generation I'm exploring.

Try it

• 🔗 GitHub (MIT): https://github.com/AneVisser/qed-framework
• 📖 Full documentation: https://anevisser.github.io/qed-framework/

The docs cover prerequisites, DSL usage, page object composition, REST setup, CI/CD configuration, and the design philosophy in detail. Feedback, issues, and stars all welcome.

If you've built something similar or hit the same walls with existing frameworks — I'd genuinely like to hear about it in the comments.