QA Master User Manual

1. Getting Started

Creating Your Account

Navigate to the QA Master home page and click Get Started. Fill in your first name, last name, email, and password, then click Register.

Once registered you will be redirected to the login page. Enter your email and password to sign in.

Forgot Password

Click Forgot Password? on the login page, enter your email, and follow the instructions sent to your inbox to reset your password.

Navigating the App

After logging in you land on the Dashboard. The bottom tab bar gives you quick access to:

• Dashboard — view and manage all your test suites
• New Suite — create a new test suite
• User Manual — this page

2. Dashboard

Overview

The Dashboard shows all your test suites as cards in a responsive grid. Each card displays:

• Suite name and description
• Testing approach badge (HTML Selector, Computer Vision, or API Only)
• Number of Test URLs and Acceptance Criteria

Actions

Pull to Refresh

On mobile, pull down on the dashboard to refresh the suite list.

3. Creating a Test Suite

Suite Configuration

Click New Suite in the tab bar or the Create New Suite button on the dashboard. Fill in:

Login Credentials

Provide the username and password that Playwright will use to log in before each test run.

Login Selectors

Tell Playwright how to find the login form elements. Provide CSS selectors for:

• Username Selector — e.g. #username or input[name="user"]
• Password Selector — e.g. #password
• Submit Selector — e.g. button[type="submit"]

Tip: If you choose the Computer Vision approach these are optional — the AI will detect them automatically.

Test URLs

Add one or more URLs that should be tested after login. These are the pages where your acceptance criteria will be executed.

User Roles

Optionally add multiple user profiles with different roles and credentials. This lets you run the same tests as different user types (admin, standard user, etc.).

Test Approach

Choose the default approach for this suite:

• HTML Selector — uses CSS/XPath selectors you provide in test steps. Fastest and most reliable.
• Computer Vision — AI analyses the page HTML to auto-detect elements. No selectors needed.
• API Only — no browser at all. Each test runs as HTTP requests against your API.

API Testing

For the API approach, set the API Base URL that step paths resolve against, and how requests authenticate: none, HTTP Basic with the suite credentials, a static bearer token, an API key in a custom header, or a login request that POSTs the credentials and reuses the returned token.

API-only suites don't need the browser login fields — only Basic and Login Request auth read the credentials.

4. Acceptance Criteria

What Are Acceptance Criteria?

Acceptance criteria define what your tests verify. They follow the Given / When / Then (Gherkin) format used in behaviour-driven development (BDD).

Creating a Criterion

From the suite detail page, click Add Criteria. Fill in:

Editing & Deleting

Expand any criterion on the suite detail page to edit its fields or delete it entirely.

5. Test Steps

What Are Test Steps?

Test steps are the executable actions that Playwright performs for each acceptance criterion. They run in order after the automated login.

Adding Steps

Expand a criterion on the suite detail page and click Add Step. Each step needs:

Available Actions

Reordering Steps

Use the up/down arrows on each step to change execution order. Steps always run sequentially from step 1 onwards.

Best Practices

• Keep steps atomic — one action per step
• Add WAIT steps after navigation to let pages load
• Use ASSERT_* steps to verify expected state
• Enable screenshots at key verification points
• Prefer ID selectors (#submit-btn) over class selectors (.btn)

6. AI Test Generation

Overview

QA Master can use AI (powered by Claude) to automatically generate acceptance criteria and test steps. There are several generation modes:

Auto-Generate from Website

From the suite detail page, click Auto-Generate Tests. The AI will:

1. Crawl the pages listed in your Test URLs
2. Analyse the HTML structure and interactive elements
3. Generate acceptance criteria in Given/When/Then format
4. Create executable test steps with selectors

You can watch the generation progress in real-time via the streaming log.

Generate from Description

Provide a plain-English description of what you want to test (e.g. "Test that a user can search for products and filter by price") and the AI converts it into structured criteria and steps.

Generate Steps for a Single Criterion

If you have written the Given/When/Then but don't want to manually add steps, click Generate Steps on an individual criterion. The AI analyses your criterion text and the target page to produce executable steps.

Generate All Steps

Click Generate All Steps to have the AI create steps for every criterion in the suite that doesn't already have steps.

Requirements

AI generation requires an AI provider key: add your own free-tier key in Settings, or set AI_API_KEY on the server. QA Master defaults to a free OpenAI-compatible provider (Groq), and also works with OpenRouter, Cerebras, or a local Ollama server. An Anthropic key remains supported as an optional paid fallback.

7. Running Tests

Starting a Test Run

Click Run Tests on a suite card (dashboard) or the Run Tests button on the suite detail page. This opens the Test Runner.

Configuration Options

Mobile and Tablet Devices

Each suite has a default Device, set when you create it or changed with Change next to Device on the suite page. A run can pick a different one in its Test Configuration.

Phone and tablet devices emulate the device's screen size, pixel density, touch input and mobile browser identity, so your site serves its mobile layout. On touch devices every CLICK step is performed as a tap. AI crawls use the suite's device too, so generated selectors match the mobile layout. Videos and screenshots are recorded at the device's screen size, and the results page shows which device a run used.

Custom size runs a desktop browser at any width and height from 240 to 3840 pixels, for checking breakpoints.

This is emulation in Chromium, not a real phone: it catches responsive layout problems, hidden or collapsed menus and touch-only controls, but not bugs that only appear on real hardware or in the real iOS Safari engine.

Live Execution Logs

While tests run, a terminal-style log panel streams step-by-step output in real time. Log prefixes include:

Stopping a Run

Click Stop to cancel a running test. The run will be marked as cancelled and any completed results will be preserved.

8. Testing Approaches

HTML Selector Approach

Uses precise CSS selectors (IDs, classes, attributes) to locate elements. This is the fastest and most reliable approach.

Selector priority (best to worst):

1. #element-id — ID selectors (most reliable)
2. [data-testid="name"] — test-specific attributes
3. button[type="submit"] — attribute selectors
4. .class-name — class selectors (can change)
5. div > span:nth-child(2) — structural selectors (fragile)

Best for: your own apps, CI/CD pipelines, regression testing, high-reliability production tests.

Computer Vision Approach

AI analyses the page HTML in real time to find interactive elements without predefined selectors.

Detection strategies:

• Form fields: by input type, placeholder text, name attribute, associated label, proximity to descriptive text
• Buttons/links: by role, text content, value attribute, ARIA labels

Fallback chain: text matching → role matching → structural analysis → HTML selector (if provided) → fail with remediation.

Best for: third-party apps, exploratory testing, unknown page structures, rapid prototyping.

API Only Approach

Skips the browser entirely: each test's steps are sent as HTTP requests to your API and checked against the response. No video, no screenshots, no selectors — which makes it fast enough for a post-deploy smoke check and light enough for small servers.

Step actions:

• API_REQUEST — sends a request (method, path, headers, body) and optionally asserts the status
• ASSERT_STATUS — checks the last status: 200, a list like 200,201, or a class like 2xx
• ASSERT_JSON_PATH — checks a path such as $.data.items[0].id exists, and matches a value when you give one
• ASSERT_HEADER / ASSERT_BODY_CONTAINS — checks a response header or body text
• ASSERT_RESPONSE_TIME — checks the request finished within a millisecond budget
• EXTRACT_JSON_PATH — captures a value for reuse as {{name}} in any later step

The assertion actions all read the last response, so start each test with an API_REQUEST. Selector verification is skipped for API runs — there are no selectors to check.

Best for: REST/JSON APIs, deploy smoke checks, contract-style assertions, memory-constrained environments.

Try it: the bundled mock API

QA Master serves its own practice API at /api/mock, and ships a seeded Mock API project with a suite already pointed at it. Open that project and hit Run Tests — nothing to configure, nothing external to sign up for.

The mock has a login endpoint that returns a token, a product catalogue, a writable orders resource, and endpoints that return any status code you ask for or respond after a delay — enough to exercise every API step action, including the failure cases. Demo credentials are [email protected] / qa-password, or the API key qam-demo-key.

Its data lives in memory and resets when the app restarts, so you can create and delete freely.

Combining Approaches

1. Start with Computer Vision to discover the page
2. Review detected selectors in diagnostic logs
3. Refine criteria with exact selectors
4. Switch to HTML Selector for production runs

API tests sit alongside the browser ones: keep a fast API suite for every deploy and run the browser suites when the UI changes.

9. Results & Reports

Test Results Page

After a run completes, click View Results to see the summary:

• Total tests — number of acceptance criteria executed
• Passed / Failed — colour-coded counts
• Pass rate — percentage bar
• Duration — total execution time

Individual Test Result

Click on any result row to open the detail view showing:

• Status — PASSED, FAILED, ERROR, or SKIPPED
• Duration — how long this test took
• Step logs — step-by-step execution log
• Error message & stack trace — (for failures)
• AI Remediation — suggested fix generated by AI

Artifacts

AI Failure Remediation

When a test fails, QA Master can use AI to analyse the error and suggest fixes. The remediation appears on the test result detail page and includes actionable steps to resolve the issue.

10. Multi-User Testing

Overview

QA Master supports testing with multiple user profiles per test suite. This is useful for verifying role-based access control, different permission levels, or testing with different account types.

Adding User Profiles

When creating or editing a test suite, scroll to the User Roles section and click Add User. Provide:

How It Works

During a test run, Playwright logs in with the default user (or the suite's base credentials if no users are configured). Future updates will allow selecting which user profile to use per run.

11. Subscription & Billing

Pro Plan

QA Master offers a Pro plan at £12/month (billed annually at £144/year) that includes:

• Unlimited test suites
• AI-powered test generation
• Computer vision testing
• Video & screenshot capture
• PDF & CSV reports
• Real-time execution logs
• Multi-user test profiles
• AI failure remediation
• Priority support

Managing Your Subscription

Navigate to the Subscription page to:

• Subscribe or upgrade your plan
• View your current subscription status
• Manage billing via the Stripe customer portal
• Cancel your subscription

12. Troubleshooting & FAQ

Common Issues

Tests timing out

• Increase the wait time on steps that follow navigation
• Ensure the target website is accessible from the server
• Check if the site uses lazy-loading that needs extra wait time
• Review the diagnostic log for the specific step that timed out

Selector not found

• Open the target page in your browser and use DevTools (F12) to verify the selector
• Try a more specific selector (prefer IDs over classes)
• Check if the element is inside an iframe
• Try the Computer Vision approach — it can adapt to changed selectors

Login failed

• Verify the credentials are correct by logging in manually
• Double-check the login URL and selectors
• Check if the site uses CAPTCHA or multi-factor authentication (not supported)
• Add wait time after filling credentials to allow the form to process

AI generation not working

• Ensure an AI provider key is configured — your own key in Settings, or AI_API_KEY on the server
• Verify the API key is valid and has sufficient quota
• Check the server logs for any API errors

Diagnostic Log Prefixes

Getting More Help

If you're stuck, check the step logs and diagnostic log for your test run — they contain detailed information about what happened at every step. The AI remediation on failed tests also provides actionable suggestions.