zosma-qa

The open-source QA platform — Web, Mobile, Backend, and Load testing. Zero config. AI-native.

Drop your tests in. Everything works.

---

What is zosma-qa?

zosma-qa is a unified QA framework that gives you production-ready test infrastructure in minutes — across your entire stack. One CLI, one config, every test type.

Test Type	Runner	Status
Web (E2E & Component)	Playwright	Available
Mobile (iOS & Android)	Appium + WebdriverIO	Available
Load & Performance	k6	Available
Load & Performance	Artillery	Planned
REST API	Supertest / Pactum	Planned
Accessibility	axe-core + Playwright	Planned
Visual Regression	Percy / Chromatic	Planned

Why zosma-qa?

• Zero boilerplate — npx zosma-qa init, answer a few questions, start testing
• TypeScript and Python — pick your language at init time
• First-class AI agent support — planner, generator, and healer agents work out of the box
• Extensible plugin architecture — every runner implements a shared ZosmaPlugin interface
• One command — npx zosma-qa run dispatches to the right runner automatically

---

Packages

Package	npm	Description
zosma-qa		CLI entry point (npx zosma-qa)
@zosmaai/zosma-qa-core		Shared types, config loader, plugin interface
@zosmaai/zosma-qa-playwright		Playwright runner and base config
@zosmaai/zosma-qa-cli		Interactive CLI with prompts
@zosmaai/zosma-qa-appium		Appium mobile testing runner
@zosmaai/zosma-qa-k6		k6 load testing runner

---

Quick Start

Web Testing (Playwright)

npx zosma-qa init
# Choose: TypeScript → enter your base URL → pick browsers → set up AI agents
npx zosma-qa run
npx zosma-qa report

Or install as a dependency in an existing project:

npm install -D @zosmaai/zosma-qa-playwright @playwright/test

// playwright.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-playwright';

export default defineConfig({
  use: { baseURL: 'https://www.myapp.com' },
  browsers: ['chromium', 'firefox'],
});

See the full guide: Getting Started with Playwright

---

Mobile Testing (Appium)

Test iOS and Android apps with a Playwright-like API:

npm install -D @zosmaai/zosma-qa-appium

// tests/login.appium.ts
import { test } from '@zosmaai/zosma-qa-appium';
import { tapButton, fillInput, expectText } from '@zosmaai/zosma-qa-appium';

test.describe('Login Flow', () => {
  test('should login with valid credentials', async ({ driver }) => {
    await fillInput(driver, 'user@example.com', { testID: 'email-input' });
    await fillInput(driver, 'password123', { testID: 'password-input' });
    await tapButton(driver, { testID: 'login-button' });
    await expectText(driver, 'Welcome back');
  });
});

// zosma.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-core';

export default defineConfig({
  plugins: ['appium'],
  baseURL: 'localhost',
  browsers: ['chromium'],
});

See the full guide: Getting Started with Appium

---

Python (pytest-playwright)

npx zosma-qa init
# Choose: Python

If uv is installed, pytest-playwright is installed automatically. Otherwise the CLI prints setup instructions.

playwright install
npx zosma-qa run        # auto-detects uv.lock → uses `uv run pytest`

Scaffolded files:

tests/test_seed.py   ← seed test with page fixture
conftest.py          ← shared fixtures
pyproject.toml       ← pytest config + pytest-playwright dependency
zosma.config.ts      ← plugins: ['pytest']

---

Load Testing (k6)

npm install -D @zosmaai/zosma-qa-k6

// zosma.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-core';

export default defineConfig({
  plugins: ['k6'],
  testDir: './k6',
  baseURL: 'http://localhost:3000',
});

Write k6 scripts in ./k6/ (e.g. smoke.k6.js) or let the runner auto-generate them from endpoint configs.

npx zosma-qa run

See the full guide: Getting Started with Load Testing

---

CLI Reference

Command	Description
npx zosma-qa init	Interactive scaffold — language, baseURL, browsers, AI agents
npx zosma-qa run	Run all tests (auto-detects runner from config)
npx zosma-qa run --grep "checkout"	Run tests matching a pattern
npx zosma-qa run --headed	Run in headed (visible) browser mode
npx zosma-qa run --project firefox	TypeScript only — run a specific browser project
npx zosma-qa agents init	Set up Playwright AI agent definitions (TypeScript only)
npx zosma-qa report	Open the HTML report in the browser

---

AI Agents

zosma-qa integrates with Playwright's built-in AI agents: planner, generator, and healer.

AI agent scaffolding is currently TypeScript-only. Python projects can still use AI tools directly with tests/test_seed.py as the entry point.

Setup

npx zosma-qa agents init
# Prompts: OpenCode (default) / Claude Code / VS Code

Usage

Use the planner agent. Seed: tests/seed.spec.ts.
Generate a plan for the guest checkout flow.

Use the generator agent with specs/checkout.md

Use the healer agent on tests/checkout/add-to-cart.spec.ts

Agent definitions are stored in .github/agents/ following Playwright conventions.

---

Examples

Web: testing zosma.ai

A complete Playwright test suite is in examples/zosma-ai/:

Test file	What it tests
tests/seed.spec.ts	Homepage loads, brand visible — AI agent entry point
tests/home.spec.ts	Hero, nav, CTA, How It Works, FAQ, footer
tests/about.spec.ts	Team cards, Our Story, Our Values
tests/openzosma.spec.ts	Product page, GitHub links, tech stack
tests/contact.spec.ts	Full form fill + submit (network mocked)

pnpm test:examples

Mobile: Appium demo

A sample Appium test project is in examples/appium-demo/. It demonstrates test structure, fixtures, and agent-friendly helpers for React Native apps.

cd examples/appium-demo
cat tests/login.appium.ts

See the example README for prerequisites and setup.

---

Configuration

TypeScript projects (Playwright)

// playwright.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-playwright';

export default defineConfig({
  use: { baseURL: process.env.BASE_URL ?? 'http://localhost:3000' },
  browsers: ['chromium', 'firefox', 'webkit'],
});

// zosma.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-core';

export default defineConfig({
  plugins: ['playwright'],
  testDir: './tests',
  baseURL: 'http://localhost:3000',
  browsers: ['chromium'],
});

Mobile projects (Appium)

// zosma.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-core';

export default defineConfig({
  plugins: ['appium'],
  baseURL: 'localhost',
  browsers: ['chromium'],
});

Python projects

# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
base_url = "http://localhost:3000"
addopts = "--browser chromium"

---

Monorepo Structure

zosma-qa/
├── packages/
│   ├── core/          @zosmaai/zosma-qa-core        — types, config, plugin interface
│   ├── playwright/    @zosmaai/zosma-qa-playwright   — Playwright runner + base config
│   ├── appium/        @zosmaai/zosma-qa-appium       — Appium mobile runner + test helpers
│   ├── k6/            @zosmaai/zosma-qa-k6           — k6 load testing runner
│   ├── cli/           @zosmaai/zosma-qa-cli          — interactive CLI
│   └── zosma-qa/      zosma-qa                       — CLI entry point wrapper
├── templates/
│   ├── playwright/                — TypeScript scaffold
│   └── playwright-python/        — Python scaffold
├── examples/
│   ├── zosma-ai/                  — Playwright tests against zosma.ai
│   └── appium-demo/               — Appium mobile test examples
├── tests/                         — your tests go here
├── specs/                         — AI planner output
├── .github/
│   ├── agents/                    — Playwright agent definitions
│   └── workflows/                 — CI/CD (ci.yml, release.yml)
└── docs/

---

Docs

Getting Started Guides

• Getting Started with Playwright — web & component testing
• Getting Started with Appium — iOS & Android mobile testing
• Getting Started with Load Testing — k6 & Artillery (planned)

Reference

• Architecture
• Getting Started (General)
• Vision & Roadmap

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a PR.

License

Apache 2.0 — see LICENSE.