Database Steps

How to add database verification steps to your test cases — run SQL queries, store results in variables, and assert expected values.

Who is this for? SDETs and testers who need to verify backend data directly by running SQL queries during test execution.

Database steps let you execute SQL queries against a configured database environment and verify the results — all within a test case. Use them to confirm that a UI action actually wrote the correct data, to set up preconditions by checking existing records, or to validate data transformations that are not visible in the UI.

Prerequisites

• You have created or opened a test case.

• A database environment is configured in Settings -> Environments with type: Database and valid connection credentials.

• You are familiar with the Test Steps Editor basics.

---

Adding a database step

1. Open a test case and click Add Step.

2. In the step builder sidebar, select Database.

3. Configure the fields described below.

4. Click Create Step to add the step to your test case.

---

Fields

Field	Required	Description
Database Environment	Yes	Select the database environment to connect to. Only environments configured with type: Database appear in this dropdown.
Normal Environment	No	Select a standard environment for variable resolution. Use this when your queries reference environment variables like ${ENV.TABLE_PREFIX}.
Queries	Yes	One or more SQL queries to execute. Each query has its own variable name and optional assertions.

Query configuration

Each query row contains:

Field	Description
Query	The SQL statement to execute. Supports variable substitution: SELECT * FROM users WHERE email = '${userEmail}'.
Variable Name	The variable that stores the query result. Reference it in later steps with ${variableName}.
Assertions	Optional verification rules applied to the query result (see below).

Assertions

Each query can have one or more assertions to verify the returned data:

Field	Description
JSON Path	Path to the value in the result set to verify (e.g., $.rows[0].status).
Verification Type	The comparison operator. Default: equals.
Expected Type	The data type of the expected value: string, number, boolean, null, object, or array.
Expected Value	The value to compare against.

---

Running a query preview

Before saving the step, you can test your query directly in the step builder:

1. Enter your SQL query and select the Database Environment.

2. Click the Run Query button.

3. The query executes against the selected database, and the results display below the query field.

Use this to verify your query syntax and confirm the data you expect is present before adding assertions.

---

Example: Verify a user was created

Step 1 (AI Agent): Navigate to the registration page
Step 2 (AI Agent): Fill in the registration form with test data
Step 3 (AI Agent): Click the Submit button
Step 4 (AI Verification): Verify the success message is displayed

Step 5 (Database):
  Database Environment: QA Database
  Query: SELECT email, status FROM users WHERE email = '${testEmail}'
  Variable: newUser
  Assertion: $.rows[0].status equals string "active"

After execution, reference the stored result in later steps:

• ${newUser.rows[0].email} — the email value from the first row

• ${newUser.rows[0].status} — the status value from the first row

---

Example: Validate data after an API call

Step 1 (REST API): POST ${ENV.BASE_URL}/api/orders
  Body: { "product": "Widget A", "quantity": 3 }
  Store response in: orderResponse

Step 2 (Database):
  Database Environment: QA Database
  Query: SELECT quantity, total_price FROM orders WHERE id = '${orderResponse.body.orderId}'
  Variable: orderRecord
  Assertion 1: $.rows[0].quantity equals number 3
  Assertion 2: $.rows[0].total_price equals number 29.97

---

Advanced settings

Setting	Description
Skip Step	Skip this step during execution without removing it from the test case.
Mark as Optional	If enabled, a failure on this step does not fail the overall test case.

---

Tips & best practices

• Use environment variables in queries to keep test cases portable across environments. Reference ${ENV.DB_SCHEMA} or ${ENV.TABLE_PREFIX} instead of hardcoding schema names.

• Add a wait step before database verification if the data is written asynchronously. The UI action may return before the database commit completes.

• Use the Run Query preview to validate your SQL syntax before saving the step. This prevents execution failures caused by typos in column or table names.

• Keep queries read-only. While the step executes arbitrary SQL, avoid INSERT, UPDATE, or DELETE statements in verification steps. Use REST API steps for data setup and teardown.

• Combine with assertions to make database steps true verification steps. A query without assertions only stores data — it never fails on its own.

Troubleshooting

The Database Environment dropdown is empty No environments with type: Database are configured. Go to Settings -> Environments, create a new environment, and set its type to Database with valid connection credentials (host, port, database name, username, password).

Query fails with a connection error Verify the database credentials in the environment configuration. Ensure the database server is accessible from the ContextQA execution network. If running behind a firewall, confirm that the execution agent has network access to the database host and port.

Assertions pass but the data looks wrong Check the JSON path syntax. Query results are returned as a JSON object — use $.rows[0].columnName to access the first row. Use the Run Query preview to inspect the exact result structure before writing assertions.

Related pages

• Test Steps Editor

• Environments

• Test Data Management

• Creating Test Cases

70% less manual test maintenance with AI self-healing. Book a Demo → — See ContextQA create and maintain tests for your web application.