Quickstart

This guide walks you through a typical QA session. It assumes you have already completed the Installation steps and have aqua’s MCP server connected to your coding agent.

How aqua Works

You use aqua through your coding agent. Rather than writing test scripts by hand, you describe what you want to test in natural language, and the agent builds and runs the QA plan for you.

A typical session looks like this:

Step	You	Agent
1. Start a session	Open a coding agent session	Verifies project setup
2. Set up environment	Describe the test target	Creates an environment file
3. Create a QA plan	Describe what to test	Reads your codebase and builds a plan
4. Review and refine	Give feedback on the plan	Adjusts the plan
5. Execute	Ask the agent to run it	Executes the plan and reports results
6. Save knowledge	—	Saves insights to project memory

1. Start a QA Session

Open a new session with your coding agent. Since QA planning requires the agent to read through your codebase extensively, we recommend using a dedicated session separate from your regular development work. See Installation for setup instructions.

The agent will verify that aqua is configured correctly for your project. If anything is missing, it will let you know.

Example prompt:

Check if aqua is set up for this project.

2. Set Up the Test Environment

Tell the agent about the environment you want to test against — the target URL and any credentials needed.

Example prompt:

The local API server is running at http://localhost:3000. Set up an environment called “local” for it.

The agent creates an environment file at .aqua/environments/local.json containing the target URL and any variables needed for your tests. This file is stored locally in your project and is reusable across sessions — you only need to set it up once per environment.

If you already have environments from a previous session, you can skip this step. The agent can list existing environments and use them directly.

For details on environment configuration including secrets and proxy settings, see the Environments guide.

3. Create a QA Plan

Describe what you want to test. You can be as broad or specific as you like — the agent will read through your codebase to understand the application structure and build appropriate test scenarios.

Example prompts:

Create a QA plan for the user registration API. Cover the happy path and common error cases like duplicate emails and missing required fields.

I just added a new checkout flow in this PR. Create a QA plan that tests the full purchase process including cart, payment, and order confirmation.

Create a browser test plan for the login page. Test with valid credentials, invalid password, and locked account.

The agent will present the QA plan for your review. Each plan contains one or more scenarios, and each scenario has a series of steps — HTTP requests or browser actions with assertions.

Review the plan and give feedback. For example:

Add a scenario that tests what happens when the payment gateway times out.

The login page uses data-testid="login-button" instead of a submit button. Update the selector.

The agent will adjust the plan based on your feedback. In practice, you will often discover issues by executing the plan first and then refining it based on the results — fixing incorrect selectors, adjusting assertions, or adding missing scenarios. This cycle of execute, review, and refine is a normal part of building a reliable QA plan.

For more on how QA plans are structured, see the QA Plans guide.

4. Execute the Plan

Once you are happy with the plan, ask the agent to run it.

Example prompt:

Execute the plan against the local environment.

The agent runs each scenario and step, then reports a summary of the results — which steps passed, which failed, and any error details. You can also view the full results in the aqua Web UI.

You can also execute plans directly from the CLI without going through the coding agent. See the CLI reference for details.

For more on execution, reviewing results, and re-running plans, see the Execution guide.

5. Save Project Memory

At the end of a session, the agent saves useful insights to project memory — a persistent knowledge base shared across sessions. This might include:

• Reliable CSS selectors for UI elements
• Authentication flow details
• Known quirks or constraints of the application
• Tips for writing tests against this codebase

The next time you (or a teammate) start a QA session, the agent reads project memory to build on previous knowledge rather than starting from scratch.

For more on project memory, see the Project Memory guide.

What’s Next

• QA Plans — Understand the plan data model, versioning, and status lifecycle.
• Environments — Configure target URLs, secrets, and proxy settings.
• Execution — Learn about plan execution, result collection, and the web dashboard.
• CLI Reference — Complete reference for all aqua-cli commands and options.