Execution

Once you have a QA plan ready, you can execute it in two ways: ask your coding agent to run it, or execute it directly from the CLI. Both methods resolve secrets locally and never send raw credentials to the aqua server.

Through Your Coding Agent

The most common way to execute a plan is through your coding agent. Simply ask it to run the plan against a specific environment.

Example prompt:

Execute the QA plan against the local environment.

The agent calls the execute_qa_plan MCP tool, which:

1. Loads the environment file and resolves variables and secrets locally.
2. Runs each scenario and its steps in order, respecting dependencies.
3. Records the results on the aqua server.
4. Returns a markdown summary with pass/fail status for each step.

After execution, the agent can help you interpret the results, identify failures, and adjust the plan accordingly.

Async Execution

For long-running plans, you can use async execution to start the plan in the background and check progress later:

Execute the QA plan against the staging environment asynchronously.

The agent calls execute_qa_plan with the async parameter set to true. Instead of waiting for all scenarios to complete, it returns immediately with an execution ID and URL.

To check progress:

Check the progress of that execution.

The agent calls get_execution_progress with the execution ID, which returns:

• Current status (pending, running, completed, failed)
• Progress count (completed steps / total steps)
• Currently running step (if any)
• Per-step results as they complete

This is useful when a plan has many scenarios or steps that take a long time to execute, as it frees the agent to work on other tasks while the execution runs.

Secrets are never exposed to the agent

When the agent triggers an execution, secrets are resolved locally on your machine by the aqua MCP server process — not by the AI agent itself. The agent never sees raw secret values. It only receives the execution summary after secret values have been masked with ***.

You can safely use secrets such as API keys, passwords, and tokens in your QA plans without concern about them being sent to the AI model.

From the CLI

You can also execute plans directly from the command line using the aqua-cli execute command:

npx @aquaqa/cli execute <qa_plan_id> --env <name>

Options

Option	Description
<qa_plan_id>	(required) The ID of the QA plan to execute.
--env <name>	Load environment variables from .aqua/environments/<name>.json.
--plan-version <n>	Execute a specific plan version. Defaults to the latest version.
--var key=value	Override a variable value. Can be specified multiple times.

Use in CI/CD

CLI execution does not require a coding agent or an MCP server, making it suitable for automated pipelines. You can integrate aqua into your CI/CD workflow to run QA plans on every deploy or pull request.

Example: GitHub Actions

- name: Run QA plan
  run: npx @aquaqa/cli execute ${{ vars.QA_PLAN_ID }} --env ci

Set up a ci environment file (.aqua/environments/ci.json) with the appropriate target URLs and credentials for your CI environment. Use the env secret type to read sensitive values from CI environment variables.

Execution Flow

When a plan is executed, aqua processes it as follows:

1. Variable resolution — Variables are merged from three sources in priority order: execution overrides (highest), environment file, and plan defaults (lowest). See Template Variables for details.
2. Secret resolution — Only secrets that are actually referenced in the plan are resolved. Secret values are masked with *** before any data is sent to the server.
3. Scenario execution — Scenarios are executed in order. If a scenario declares a requires field and the required variables are not present, the scenario is skipped.
4. Step execution — Steps within each scenario are executed in order, respecting depends_on constraints. If a dependency step has failed or was skipped, the dependent step is also skipped.
5. Condition evaluation — If a step has a condition field, the condition is checked after dependency resolution. If the condition is not met (e.g., a variable does not equal the expected value), the step is skipped. See Conditional Step Execution for details.
6. Assertions — After each step completes, its assertions are evaluated. A step passes if all assertions succeed.
7. Extraction — Values extracted from step responses become available as template variables for subsequent steps.

Cross-Scenario State

State is shared across scenarios in two ways:

• Extracted variables are global — a value extracted in one scenario can be referenced in any subsequent scenario.
• Browser state (cookies and localStorage) is preserved across scenarios, so a login performed in one scenario carries over to the next.

Reviewing Results

In the Agent Session

After execution, the agent presents a summary showing:

• Overall pass/fail status
• Per-scenario and per-step results
• Error details for failed steps
• A link to the full results in the aqua Web UI

You can ask the agent to dig deeper into specific failures:

What went wrong with the “checkout with expired card” scenario?

In the Web UI

The aqua Web UI provides a detailed view of each execution, including:

• Full request and response data for HTTP steps
• Screenshots and browser logs for browser steps
• Assertion results with expected vs. actual values
• Execution timeline

Open the Web UI with:

npx @aquaqa/cli web

Via MCP Tools

The agent can also use the get_execution and list_executions MCP tools to retrieve past execution results programmatically. This is useful for comparing results across runs or tracking down regressions.

Sharing Results

You can share execution results with team members, stakeholders, or anyone else — even people who don’t have an aqua account. Shared links provide a read-only view of the full execution results including scenarios, steps, assertions, and artifacts.

Creating a Share Link

1. Open the execution detail page in the Web UI.
2. Click the Share button in the top-right corner.
3. Choose an expiration period (3 days or 30 days).
4. Click Create share link.
5. Copy the link and share it with anyone.

The share link provides full access to the execution results without requiring login. Each execution can have one active share link at a time.

Revoking a Share Link

If you need to revoke access to a shared execution:

1. Open the execution detail page and click Share.
2. Click Revoke share link at the bottom of the dialog.

The link creator or any organization admin can revoke a share link. Once revoked, the link immediately stops working.

What’s Included

The shared view includes:

• Execution status and timing information
• All scenarios with their step results
• Assertion results (pass/fail with expected vs. actual values)
• Artifacts (HTTP request/response data, screenshots)
• Environment variables (secrets are already masked with *** before recording)

Re-Running Plans

After fixing issues in your plan or application, you can re-run the plan immediately:

Run the plan again against the local environment.

You can also run a specific version of the plan:

npx @aquaqa/cli execute <qa_plan_id> --env local --plan-version 3

Or override specific variables for a one-off run:

npx @aquaqa/cli execute <qa_plan_id> --env local --var api_base_url=http://localhost:4000

Automatic Status Transitions

When an execution completes with all steps passing, the plan’s status is automatically promoted from draft to active. This ensures that only validated, fully passing plans carry the active status.

Conversely, when a new version is added to an active plan, the status is automatically demoted back to draft for re-validation.

See QA Plans for more on the status lifecycle.