Getting Started

Install QA Studio, start the development server, and create your first automated browser test in under five minutes.

Prerequisites

Before installing QA Studio, make sure your system meets the following requirements:

Requirement	Version	Notes
Node.js	20 or higher	Required. LTS version recommended.
pnpm	8 or higher	Required. Used for workspace management.
Google Chrome	Latest stable	Optional. Needed only for Real Browser mode.
Operating System	macOS, Linux, Windows	Any OS that supports Node.js and Playwright.

If you do not have pnpm installed, you can install it globally via npm:

bash

npm install -g pnpm

Installation

Clone the repository and install all dependencies with a single command. QA Studio is a monorepo managed by pnpm workspaces, so all three packages (server, dashboard, and shared types) are installed together.

bash

git clone <repo-url>
cd qa-studio
pnpm install

This installs dependencies for all three packages:

apps/server — Fastify API server with Playwright, SQLite (Drizzle ORM), and Zod validation
apps/dashboard — React 18 frontend with Vite, TanStack Query, dnd-kit, and Tailwind CSS
packages/shared — TypeScript-only types package (@qa-studio/shared)

Next, run the setup script to install Playwright browsers and initialize the SQLite database:

bash

pnpm setup

This command downloads Chromium, Firefox, and WebKit browser binaries that Playwright uses for test execution. The SQLite database is created automatically on first server start.

Running the Dev Server

Start both the API server and the dashboard in development mode with a single command:

bash

pnpm dev

This starts both services concurrently. Here are the default URLs:

Service	URL	Description
Dashboard	`http://localhost:5173`	React frontend with visual test builder, recorder, and analytics
API Server	`http://localhost:3001`	Fastify REST API with SSE streaming for live run progress

Open http://localhost:5173 in your browser to access the QA Studio dashboard.

Info

The SQLite database file is created automatically in the server directory on first startup. No additional database setup is required.

Your First Test

Follow these steps to create and run your first automated browser test:

Create a Project

From the dashboard home screen, click New Project. Enter a name (e.g., "My Website") and an optional base URL. The base URL is used as the default starting point for all tests in this project.

Create a Test

Inside your project, click New Test. Give it a descriptive name like "Homepage Load Test" or "Login Flow". This opens the Test Builder where you will define your test steps.

Add Steps

Use the Action Palette on the left panel to add steps to your test. For a basic navigation test, start with these steps:

Example Steps

{
  "steps": [
    { "action": "goto", "url": "https://example.com" },
    { "action": "assert", "assertType": "title", "condition": "contains", "value": "Example" },
    { "action": "click", "selector": "a", "selectorMode": "css" },
    { "action": "screenshot", "name": "after-click", "fullPage": true }
  ]
}

Each step is a card in the center panel. Click on any step card to edit its properties in the right panel.

Run the Test

Click the Run button in the top toolbar. QA Studio automatically saves your test before execution. The test runs in a headless Playwright browser by default, and you can watch each step execute in real-time thanks to SSE streaming.

Each step card updates with a status indicator as it executes:

Running — Blue spinner, step is currently executing
Passed — Green checkmark, step completed successfully
Failed — Red X, step encountered an error
Skipped — Gray dash, step was skipped (e.g., inside a false conditional branch)

View Results

After the run completes, you can view the full results including:

Overall pass/fail status and execution duration
Per-step results with error messages and screenshots
Console logs captured during execution
Visual regression diffs (if screenshot steps were included)

Results are stored in the SQLite database and accessible from the test's run history.

Tip: Real Browser Mode

If your target website has bot detection or requires specific browser features, enable Real Browser mode in the test configuration. This launches a real Google Chrome instance instead of Playwright's bundled Chromium, which can bypass many anti-bot measures. You must have Chrome installed on your machine for this to work.

Info: Recording Shortcut

Instead of manually adding steps, you can use the Recorder to capture browser interactions automatically. Click the record button in the test builder toolbar, enter a starting URL, and interact with the page. QA Studio captures your clicks, text inputs, selections, and navigations as test steps in real-time. See the Recording page for details.

Project Structure

Understanding the monorepo layout helps when you want to customize or extend QA Studio:

Project Layout

qa-studio/
├── apps/
│   ├── server/           # Fastify API + Playwright runner
│   │   ├── src/
│   │   │   ├── db/       # SQLite schema, migrations, queries
│   │   │   ├── routes/   # REST API route handlers
│   │   │   ├── runner/   # Test execution engine
│   │   │   └── server.ts # Server entry point
│   │   └── package.json
│   └── dashboard/        # React frontend
│       ├── src/
│       │   ├── components/  # Reusable UI components
│       │   ├── pages/       # Route-level page components
│       │   └── lib/         # API client, utilities
│       └── package.json
├── packages/
│   └── shared/           # TypeScript types (@qa-studio/shared)
├── pnpm-workspace.yaml
└── package.json

Next Steps

Now that you have QA Studio running and have created your first test, explore the rest of the documentation to unlock the full power of the platform:

Test Builder — Learn the 3-panel interface, drag-and-drop, and step editing in depth
Recording — Capture browser interactions automatically with intelligent selector generation
Actions Reference — Explore all 17 available step actions and their configuration fields
Environment Variables — Use {{variables}} for dynamic values across your tests
Test Suites — Group tests and run them in parallel with configurable concurrency

Previous ← Home Next Test Builder →