k0lmena Automation Framework documentation

Everything you need to install, configure and use the framework: front, API, mobile, performance, reports and auto-healing.

What it is and what's included

k0lmena is a QA automation framework that brings four kinds of tests into one repository with one syntax (Gherkin/BDD + TypeScript):

It also includes locator auto-healing, HTML reports for each test type, helper tools (locator generator, broken-link tester, recorder and debug mode) and automatic screenshots, traces and logs on failure.

Technologies

• TypeScript
• Playwright (E2E, tracing and codegen)
• Cucumber (@cucumber/cucumber, BDD/Gherkin)
• Axios (API)
• WebdriverIO + Appium (mobile)
• Artillery and k6 (performance)
• Cheerio (HTML parsing in tools)

Project structure

src/
├── front-test/        # E2E (UI): Playwright + Cucumber
│   ├── features/      # Gherkin scenarios (.feature)
│   ├── steps/         # Step definitions
│   ├── locators/      # Element selectors
│   ├── config/        # Config (BASEURL from .env)
│   ├── hooks/         # Browser setup, screenshots, traces
│   ├── utils/         # interactions, validations, keys, types
│   └── auto-healing/  # Locator history
├── api-test/          # features/ + tests/ (axios)
├── mobile-test/       # apps/ features/ steps/ locators/ support/
├── performance-test/  # artillery/ + k6/
├── reports/           # front/ api/ mobile/ performance/
└── tools/             # crawler/ link-tester/ generator/ debug/

Key root files: package.json, cucumber.js (profiles), playwright.config.ts, tsconfig.json, .example.env.

Prerequisites

• Node.js (LTS recommended): nodejs.org
• Visual Studio Code (optional)
• For mobile: Appium and an emulator or device (or a BrowserStack account).
• For k6 performance tests: the binary is installed with the bootstrap script.

Installation

git clone https://github.com/underc0delabs/k0lmena.git
cd k0lmena
npm install                # dependencies
npx playwright install     # Playwright browsers
cp .example.env .env       # environment file

Then edit .env with your values.

Configuration (environment variables)

General / Front

API

Auto-healing

Front / E2E (UI)

npm run test       # @Smoke scenarios, 1 retry
npm run allTests   # all tests

Cucumber profiles live in cucumber.js. Control browser and mode through variables:

BROWSER=chromium HEADLESS=false SLOWMO=300 npm run test
TRACE=on-failure npm run test

Parallel execution

PARALLEL=4 npm run test
PARALLEL=on npm run apiTest

• Each worker is an independent process; auto-healing writes one history file per worker to avoid collisions.
• The debug profile always runs sequentially.
• Parallelism is per scenario: for maximum speed, pin a single browser per run.

API

npm run apiTest   # scenarios tagged @API

Set API_BASEURL in .env.api. Steps live in src/api-test/tests/.

Mobile

npm run mobile    # WebdriverIO + Appium

Config lives in src/mobile-test/support/wdio.conf.ts. By default it runs against local Appium (localhost:4723) and includes a commented block for BrowserStack using BROWSERSTACK_USER and BROWSERSTACK_KEY.

Performance

Artillery

npm run load   # load test, writes report.json

k6

npm run bootstrap:k6     # installs the binary the first time
npm run k6:build         # compiles the TypeScript scenarios
npm run k6::smoke
npm run k6:stress
npm run k6:soak
npm run k6:spike
npm run k6:run:browser

k6 scenarios live in src/performance-test/k6/http/ and are compiled with esbuild into dist/.

Reports

When a front test fails, the framework attaches a screenshot, browser console logs and, if TRACE is on, the Playwright trace.

Locator auto-healing

k0lmena can recover locators that stop working when the app changes. It works in two phases:

1. Learn: every time an action succeeds, it stores alternative locators for the element (data-testid, id, name, aria-label, role, text, classes) in a history file.
2. Heal: if the original locator fails, it tries the stored candidates (ranked by past success and page) until one works, and reports it.

K0LMENA_AUTO_HEALING=on npm run test

When a locator is healed you'll see HEALED: <original> -> <candidate> in the console, and the event is attached to the report.

Tools

All of them use BASEURL from .env unless stated otherwise.

Crawler (locator generator)

npm run crawler
npx ts-node src/tools/crawler/locators-generator.ts https://mi-sitio.com

Output: src/tools/crawler/output/locators-output.ts

Link tester

npm run link-tester        # base page
npm run link-tester:full   # full site

Record (Playwright codegen)

npm run record
npm run record:generator

Debug

npm run debug

Continuous integration (CI)

The .github/workflows/Tests.yaml workflow runs on GitHub Actions (manual trigger) inside the official Playwright container and runs, in order: dependency and browser install, front tests + report, API tests + report, performance (Artillery) + report, and publishes the reports as artifacts.

How to add a new test

1. Feature: create or edit a .feature in src/front-test/features/.
2. Locators: add selectors in src/front-test/locators/.
3. Steps: implement them in src/front-test/steps/ using the helpers in utils/interactions.ts (getByPlaceholderAndFillIt, getElementByRoleAndClickIt, selectByLabel, click, fill).
4. Run with npm run test (or tag the scenario with @Smoke).

The interaction helpers already include auto-healing, so your steps benefit with no extra code.

npm scripts reference

Video

Watch the video tutorial on YouTube · QARMY channel

License and credits

k0lmena Automation Framework is open source under the ISC license. It is a QARMY and Underc0de community project.