# Tutorial: Data-Driven Testing

{% hint style="info" %}
**Who is this for?** Testers and SDETs new to data-driven testing in ContextQA. You will build one test case and run it across multiple data sets without duplicating anything.
{% endhint %}

Data-driven testing runs the same test case multiple times, each time with a different set of input values. Instead of creating separate test cases for "login as admin", "login as manager", and "login as viewer", you create one test case and a **test data profile** that supplies the credentials and expected outcomes for each role.

In this tutorial you will:

1. Create a login test case with variable placeholders
2. Create a test data profile with four user roles
3. Attach the profile to a test plan
4. Execute the plan and review per-row results

**End result:** One test case produces four independent execution records — one per data row — each with its own screenshots, video, and pass/fail status.

## Prerequisites

* A ContextQA account with at least one workspace ([sign up](https://accounts.contextqa.com/onboard))
* A web application with a login page you can test against
* At least two sets of valid credentials (different user roles or accounts)
* Familiarity with [creating test cases](/web-testing/creating-test-cases.md) and [running tests](/execution/running-tests.md)

***

## Step 1: Create a test case with variable placeholders

Instead of hard-coding a username and password into your test steps, use `${variable}` placeholders that ContextQA resolves at runtime from the data profile.

1. In the left sidebar, click the **Test Development** icon.
2. Click the **+** button and select **Start with AI Assistance**.
3. Enter your application's login page URL in the **Application URL** field.
4. In the **Task Description** field, write a parameterized description:

```
Navigate to the login page.
Type ${username} in the Email field.
Type ${password} in the Password field.
Click the Sign In button.
Verify that the page title contains ${expected_title}.
```

5. Click **Generate**. The AI creates steps that reference `${username}`, `${password}`, and `${expected_title}` as variable placeholders.
6. Review the generated steps. Confirm each `${variable}` reference appears exactly as you typed it — spelling and case must match the data profile column names you create in the next step.

{% hint style="info" %}
**Tip:** You can also add variable placeholders to an existing test case. Open the step editor, select a step, and replace any hard-coded value with `${variableName}`.
{% endhint %}

***

## Step 2: Create a test data profile

A test data profile is a table where each column is a variable name and each row is one complete test run.

1. In the left sidebar, navigate to **Test Development**.
2. Click the **Test Data Profiles** tab.
3. Click **+ Create Test Data Profile**.
4. Enter a profile name: `LoginScenarios_MultiRole`.
5. Click **+ Add Column** and enter `username`. Repeat to add columns for `password` and `expected_title`.

> **Important:** Column names are case-sensitive. `username` and `Username` are different variables. Match the exact spelling you used in your test steps.

6. Click **+ Add Row** four times to create four data rows. Fill in the values:

| `username`            | `password`    | `expected_title`   |
| --------------------- | ------------- | ------------------ |
| `admin@yourapp.com`   | `Admin123!`   | `Admin Dashboard`  |
| `manager@yourapp.com` | `Manager456!` | `Team Dashboard`   |
| `viewer@yourapp.com`  | `Viewer789!`  | `Reports`          |
| `billing@yourapp.com` | `Billing000!` | `Billing Overview` |

7. Click **Save**.

You now have a profile with four rows. When attached to your test case, ContextQA runs the test four times — once per row.

***

## Step 3: Create a test plan and attach the profile

Test data profiles are attached at the **test plan** level, not at the test case level. This keeps your test cases reusable — the same test case can run with different profiles in different plans.

1. Navigate to **Test Development → Test Plans**.
2. Click **+ Create Test Plan**.
3. Enter a plan name: `Login — Multi-Role Validation`.
4. Under **Test Suites**, select the suite that contains your login test case. If the test case is not in a suite yet, add it to one first (see [Managing test suites](/web-testing/managing-test-suites.md)).
5. Locate your login test case in the plan's test case list.
6. In the **Test Data Profile** dropdown next to the test case, select `LoginScenarios_MultiRole`.
7. Configure the remaining plan settings:
   * **Browser:** Select your target browser (e.g., Chrome).
   * **Environment:** Select the environment that points to your application.
8. Click **Save**.

{% hint style="warning" %}
**Common mistake:** If you skip the profile attachment and run the test case directly (outside a test plan), the `${variable}` placeholders are not resolved. The test runs once with unsubstituted variables and fails. Always run data-driven tests through a test plan with the profile attached.
{% endhint %}

***

## Step 4: Execute the test plan

1. Open the test plan you created.
2. Click **Run**.
3. ContextQA queues four executions — one for each row in the data profile.

Watch the execution progress. Each row runs independently:

* **Row 1:** Logs in as `admin@yourapp.com`, verifies "Admin Dashboard"
* **Row 2:** Logs in as `manager@yourapp.com`, verifies "Team Dashboard"
* **Row 3:** Logs in as `viewer@yourapp.com`, verifies "Reports"
* **Row 4:** Logs in as `billing@yourapp.com`, verifies "Billing Overview"

Each execution captures its own screenshots, video recording, and network logs.

***

## Step 5: Review per-row results

When all four executions complete:

1. Navigate to the test plan's execution results.
2. Each data row appears as a separate execution record with its own pass/fail status.
3. Click any execution to see the step-by-step breakdown, including:
   * The **resolved variable values** used for that row
   * Per-step screenshots showing the actual credentials typed
   * Video recording of the full browser session
   * Root cause analysis if the row failed

**What to look for:**

| Result                     | What it means                                                                     |
| -------------------------- | --------------------------------------------------------------------------------- |
| All four rows pass         | Your login flow works correctly for all tested roles                              |
| One row fails, others pass | That specific role has a unique issue — check the failure's root cause analysis   |
| All rows fail on step 1    | The login URL or page structure may have changed — the issue is not data-specific |

***

## Summary

You built a data-driven test in four steps:

1. **Created a test case** with `${variable}` placeholders instead of hard-coded values
2. **Created a test data profile** with columns matching those variable names and rows for each scenario
3. **Attached the profile** to the test case inside a test plan
4. **Executed the plan** and reviewed independent results per data row

One test case now covers four user roles. To add a fifth role, add a row to the profile — no test case changes needed.

## Next steps

* **Scale your profile:** Add more rows for edge cases — empty passwords, special characters in usernames, expired accounts. Each row becomes an automatic test run.
* **Import from a spreadsheet:** If you have test data in Excel or CSV, import it directly into a data profile instead of typing each row manually. See [Test data management](/web-testing/test-data-management.md#importing-profile-data-from-a-spreadsheet).
* **Combine with environments:** Use `${ENV.BASE_URL}` for the application URL and `${username}` from the data profile for credentials. This lets you run the same data-driven test against staging and production by switching environments in the test plan. See [Configuring environments](/execution/environments.md).
* **Add negative scenarios:** Create a second profile with invalid credentials and expected error messages. Attach it to the same test case in a different test plan to validate error handling without duplicating test steps.

## Related pages

* [Test data management](/web-testing/test-data-management.md) — reference for all variable types and scopes
* [Creating test cases](/web-testing/creating-test-cases.md) — how to create test cases with AI assistance, recording, or manual steps
* [Managing test suites](/web-testing/managing-test-suites.md) — how to organize test cases into suites
* [Configuring environments](/execution/environments.md) — how to manage environment-specific parameters
* [Running tests](/execution/running-tests.md) — how to execute test cases, suites, and plans

{% hint style="info" %}
**Run the same test across 100 data sets — no code required.** [**Start Free Trial →**](https://app.contextqa.com/register) — Or [**Book a Demo →**](https://contextqa.com/book-a-demo/) to see data-driven testing with your application.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learning.contextqa.com/web-testing/data-driven-testing-tutorial.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.