> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/web-testing/environment-data-management.md).
# Environment Data Management
{% hint style="info" %}
**Who is this for?** Testers, SDETs, and QA managers who manage the data their tests depend on — environment variables, database connections, data-driven profiles, and workspace-wide global variables — from a single place.
{% endhint %}
## Quick answer
Use **Environment & Data Management** to keep deployment-specific environments, reusable test data profiles, and workspace-wide global data separate. This lets one test run safely across development, staging, or production-like targets without duplicating steps or hard-coding URLs and input values.
## What this page covers
* An **environment** is *where* the test runs. It contains deployment-specific variables, database connections, and links to data profiles.
* A **test data profile** is *what* the test uses. It defines reusable columns and rows whose values can differ by environment.
* **Global data** contains workspace-wide values that do not change between environments.
This separation lets one test run against development, staging, or production-like targets without duplicating the test steps or hard-coding URLs and input data.
Open **Environment & Data** from the left navigation. The **Environment & Data Management** page opens on the **Environments** tab and provides three tabs:
| Tab | Manages |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Environments** | Per-environment variables, database connections, and the test data profiles linked to each environment |
| **Test Data Profiles** | Data-driven tables whose structure is shared across environments and whose values are independent per environment |
| **Global Data** | Environment-agnostic variables available to every test case in the workspace |
ContextQA inserts variables from the step editor's data picker. An environment variable named `baseURL`, for example, is referenced as `*|baseURL|*`. Choose the variable from the picker when possible so the name and syntax are inserted correctly.
[Watch the environments-and-data-profiles walkthrough](https://drive.google.com/file/d/1UbcQCoDLHLrjbau3Jfb9HqGF3lnsGR-m/preview).
## Prerequisites
* You have a workspace created with at least one environment.
* You are a workspace member with permission to edit data (Editor or Admin role).
***
## Permissions: read-only and read-write
Most values in this workspace carry a permission setting shown as a toggle:
* **RW** (read-write) — test cases and team members can both read and update the value.
* **RO** (read-only) — the value is visible and usable in test steps, but protected from edits.
Set a value to **RO** to lock down shared data — such as a stable account ID or a reference table — so that a test run or another team member cannot change it accidentally. Switch back to **RW** when you need to edit it.
***
## Variable naming rules
Every name you enter in this workspace — environment variables, global variables, and test data profile columns — must be a valid variable identifier:
* Start with a letter or an underscore (`_`).
* Use only letters, numbers, and underscores after the first character — no spaces or special characters.
* Names are case-sensitive.
* A name cannot match a reserved keyword such as `os`, `path`, `fs`, `moment`, `get`, or `post` (matched case-insensitively).
ContextQA validates the name as you type and blocks saving until it is valid; if a name is rejected, the field explains which rule it broke. See [Variable naming rules](/web-testing/test-data-management.md#variable-naming-rules) for the complete rules, the reserved-keyword list, and every error message.
***
## Environments tab
The **Environments** tab lists every environment in the workspace. Each environment is a named deployment target (for example, `Staging`, `QA`, or `Production`) that holds its own variables, database connections, and linked profiles.
### Browsing environments
* Use the **Search environments...** box to filter by name.
* Use the view toggle to switch between **grid** (cards) and **list** (table) views.
* The environment marked **DEFAULT** is used when no other environment is selected. You cannot delete the default environment.
*An environment keeps deployment-specific values together. This documentation example uses a fictional `example.test` URL and contains no production credentials.*
### Creating an environment
1. Click **New environment**.
2. Enter a **Name** and an optional **Description**.
3. Save the environment. It appears in the list, and you can open it to add variables, databases, and profiles.
### Environment actions
From an environment card or the environment detail header, you can:
* **Clone** — create a copy of the environment, including its configuration.
* **Edit details** — change the name or description.
* **Delete** — remove the environment. This is disabled for the default environment.
### Working inside an environment
Click an environment to open its detail view. The detail view has three sub-tabs:
#### Environment variables
Key-value pairs scoped to this environment. Test cases read and write them according to each variable's RO/RW permission. Reference a variable by selecting it in the step editor's data picker; for example, `baseURL` is inserted as `*|baseURL|*`.
The table shows four columns — **NAME**, **TYPE**, **VALUE**, and **PERMISSION** — plus row actions.
To add a variable:
1. Click **Add variable**.
2. Enter the **Name** and **Value**.
3. Select the **Type**:
| Type | Use for |
| ------------ | ------------------------------------------------ |
| **String** | Plain text values such as URLs and labels |
| **Number** | Numeric values |
| **Boolean** | `true` / `false` flags |
| **Password** | Sensitive values that should be masked in the UI |
| **Vault** | Sensitive values handled as vault-backed secrets |
4. Set the permission to **RW** or **RO**.
5. Save the variable.
{% hint style="warning" %}
Store credentials, API keys, and tokens as **Password** or **Vault** values. When you edit either secret type, ContextQA opens the value field blank; leave it blank to preserve the stored secret, or enter a new value to replace it. Never place real secrets in screenshots, examples, profile names, or descriptions.
{% endhint %}
#### Databases
The **Data base configurations** sub-tab connects SQL databases to the environment. You can attach multiple databases and use them alongside variables — there is no forced choice between the two.
To add a connection:
1. Click **Add DB config**.
2. Enter a **Connection name**.
3. Select the **Driver** (for example, MySQL).
4. Enter the **Host** and **Port**.
5. Save the configuration.
Database connections defined here are available to [Database Steps](/web-testing/database-steps.md) running in this environment.
#### Profiles
The **Linked test data profiles** sub-tab lists the profiles visible to test cases running in this environment. Only linked profiles appear in the step picker for this environment.
* Click **New profile** to create a profile and link it to this environment in one step.
* Click **Link profile** to attach an existing profile.
When you link an existing profile, the **Link profile** dialog lets you search profiles, select one or more, and choose a source environment under **Copy from which environment**. The selected source's row values become the starting point for this environment and can be edited afterward. A profile with no existing data is linked with no rows.
***
## Test data profiles
The **Test Data Profiles** tab manages data-driven test tables. A profile defines a set of named columns once; each linked environment then stores its own independent set of row values. The column structure is shared across environments, but the values are independent — so the same test logic can run against staging data and production data without duplicating the profile.
### Browsing profiles
* Use the **Search profiles…** field to filter by name.
* Use the environment filter to show only profiles linked to a specific environment.
* Use the permission filter to show only read-only or read-write profiles.
### Creating a test data profile
1. On the **Test Data Profiles** tab, click **New test data profile**.
2. Enter the profile **Name** and optional **Description**.
3. Save the profile.
You can also create a profile directly from an environment's **Data profiles** sub-tab using **New profile**, which links the new profile to that environment automatically.
*The profile structure is shared across environments, while each environment keeps independent row values.*
## Tutorial: create reusable registration data for a staging test
This example creates a staging environment, adds a base URL, builds a registration data profile, and connects the two. All names and values are fictional; replace them with safe values for your own non-production system.
### 1. Create the staging environment
1. Select **Environment & Data** in the left navigation.
2. On **Environments**, select **New environment**.
3. Enter `Stage Environment` as the name.
4. Add a description that tells teammates what the environment is for.
5. Save the environment, then open it from the environment list.
### 2. Add the base URL variable
1. Open the environment's **Environment variables** tab.
2. Select **Add variable**.
3. Enter `baseURL` for **Name**.
4. Select **String** for **Type**.
5. Select **RW** while you are setting up the example. Use **RO** later if the value should be protected from changes.
6. Enter a non-production URL, such as `https://example.test`, for **Value**.
7. Save the variable.
In a test step, use the data picker to insert the variable. ContextQA displays it as:
```
Navigate to *|baseURL|*
```
{% hint style="info" %}
`*|baseURL|*` is an environment-variable reference. Expressions such as `${loginResponse.body.token}` serve a different purpose: they access data stored by an earlier API or database step.
{% endhint %}
### 3. Create the registration data profile
1. Return to **Environment & Data Management**.
2. Select **Test Data Profiles**.
3. Select **New test data profile**.
4. Enter `Registration Data` as the profile name.
5. Add a description explaining that the profile contains fictional registration inputs.
6. Set the permission to **RW** while you build the profile.
7. Assign the profile to **Stage Environment**, then save it.
### 4. Define the shared columns
1. Open the new profile.
2. Select **Manage columns**.
3. Add these columns:
| Column | Type | Example purpose |
| ----------- | -------- | ------------------------- |
| `firstName` | String | User's given name |
| `lastName` | String | User's family name |
| `email` | String | Unique registration email |
| `password` | Password | Masked test-only password |
4. Apply the changes.
Column definitions are shared across every assigned environment. If you change a column type later, review the confirmation carefully: converting to **Number** or **Boolean** replaces existing values, while converting to **String** or **Password** preserves them.
### 5. Add a row for the staging environment
1. Select the **Stage Environment** tab inside the profile.
2. Select **Add row**.
3. Enter a unique row name such as `registration_1`.
4. Add fictional values, for example `Avery`, `Tester`, `avery.tester@example.test`, and a test-only password.
5. Save the row.
The same profile can now be assigned to another environment. Its columns remain the same, but you can enter different row values for that environment.
### 6. Use the environment and profile in a test
1. Open or create a test case.
2. Select **Stage Environment** as its execution environment.
3. Attach or select **Registration Data** when configuring the test's data.
4. Insert environment and profile values with the step editor's data picker.
5. Run the test and confirm that the execution used the selected environment and expected data row.
If the profile is missing from the picker, confirm that it is assigned to the selected environment.
### Editing profile data
Open a profile to view its detail page. The detail page shows one sub-tab per linked environment, each with that environment's row values.
* The banner reads **"Structure is shared across environments, values are independent"** when you view an environment tab.
* Click an environment sub-tab to edit that environment's rows.
* Click **Assign to more environments** (the **+** tab) to link the profile to additional environments.
* Click **Manage columns** to add, rename, remove, or set the data type of columns. Column changes apply across all environments because the structure is shared.
* Click **Add row** to append a row to the active environment's data.
{% hint style="info" %}
Profiles created before per-environment data may show a **master data (deprecated)** tab. These legacy rows are read-only. Assign the profile to an environment to start editing per-environment data.
{% endhint %}
### Column data types
Each profile column has a data type that controls how you enter its values and how they display in the table. Set the type when you add or edit a column in the **Manage columns** dialog — every column has a type selector, and new columns default to **String**. The type is part of the shared column structure, so it applies across all environments.
| Type | How you enter and view values |
| ------------ | ---------------------------------------------------------------------------------------- |
| **String** | Free-text input. The default for new columns. |
| **Number** | Numeric input that accepts digits and a decimal point. New cells start at `0`. |
| **Boolean** | A **True** / **False** dropdown. New cells default to **True**. |
| **Password** | A masked input. Select the reveal icon to show or hide the value. New cells start empty. |
#### Changing a column's data type
When you change an existing column's type in the **Manage columns** dialog, the **Confirm column type changes** dialog appears before the change applies. For each affected column, it shows the current type, the new type, and what happens to existing values:
* Changing to **Number** resets every value in the column to `0`.
* Changing to **Boolean** resets every value to `true`.
* Changing to **String** or **Password** keeps existing values unchanged.
{% hint style="warning" %}
Replacing values cannot be undone. Select **Apply changes** to confirm the conversion, or **Cancel** to keep the columns as they are.
{% endhint %}
### Profile detail actions
The profile detail header provides:
* A **permission toggle** to set the profile read-only or read-write.
* **Clone to environments** — copies the profile's data into other environments.
* **Edit** — changes the profile name and description.
* **Delete** — removes the profile. If the profile is linked to test cases or environments, the confirmation dialog lists them first.
***
## Global data
The **Global Data** tab manages workspace-wide variables. These variables are environment-agnostic: they are accessible from every test case regardless of which environment is selected, and their names must be unique across the entire workspace.
### Creating a global variable
1. On the **Global Data** tab, click **New global variable**.
2. Enter the variable **Name** and **Value**.
3. Select the **Type** — **String**, **Number**, **Boolean**, or **Password**.
4. Optionally add **tags** to group related variables.
5. Save the variable.
### Filtering and exporting
* Use the **Search global variables…** field to filter by name.
* Use the tag chip bar to filter by one or more tags.
* Click **Export all** and choose **Export as JSON** or **Export as Excel** to download every global variable, or select rows and click **Export** to download only those. See [Importing and exporting data](#importing-and-exporting-data) for the full workflow.
### Global variable vs environment variable
| Use a... | When the value... |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Global variable** | Is the same across every environment (a standard test product name, a default search term). |
| **Environment variable** | Differs by environment (the base URL, credentials, or API keys for staging versus production). |
***
## Importing and exporting data
Environment Data Management supports JSON and Excel (`.xlsx`) export across its environments, database configurations, profiles, and global data. Import support varies by surface, as described below. Export data to back it up, move it between workspaces, or review it offline.
{% hint style="info" %}
Treat every exported file as potentially sensitive. Review the file before sharing it, store it securely, and never use real credentials in documentation examples.
{% endhint %}
### Exporting data
Export is available from these places:
| Location | What exports | How |
| ------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Environments** tab | One or more environments, with their variables and database configurations | Click **Export all**, or select environments and click **Export** |
| An open environment | That environment's data | Click **Export** in the header, then choose what to include and a format |
| **Environment variables** sub-tab | The environment's variables only | Click **Export all** |
| **Data base configurations** sub-tab | The environment's database configurations | Click **Export all**, or select rows and click **Export** |
| **Test Data Profiles** tab | Selected profiles | Select profiles and click **Export** |
| A profile detail page | The profile's rows, for all environments or specific ones | Click **Export**, then choose a scope and a format |
| **Global Data** tab | Every global variable, or a selection | Click **Export all**, or select variables and click **Export** |
When you export an environment, a **What to include** step lets you choose:
* **All** — variables and database configurations together.
* **Variables** — environment variables only.
* **Database configs** — database configurations only.
Exporting **All** across several environments produces a `.zip` file. A single, scoped export produces one `.json` or `.xlsx` file.
### Importing data
Import is available for global variables, database configurations, test data profiles, and new environments. Direct import from an open environment's **Environment variables** section is not currently available.
| Surface | Current import workflow |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Environments** tab | Creates a new environment from separate variable and database-configuration files |
| **Data base configurations** | Imports into the open environment and provides duplicate-handling choices |
| **Test Data Profiles** | Imports profile data with the applicable environment and conflict choices |
| **Global Data** | Uploads global variables and reports the import result; it does not show a separate duplicate-handling step |
The general import sequence is:
1. Click **Import** on the relevant tab or sub-tab.
2. Upload a `.json` or `.xlsx` file. To start from a correctly structured file, download the sample template offered in the wizard for the format you want.
3. When the wizard provides a duplicate-handling step, choose the applicable strategy.
4. Confirm the import. The result step reports how many rows succeeded, how many failed, and the reason for each failure.
#### Handling duplicates
When a supported import wizard presents conflict handling, the available options depend on the surface:
| Option | What it does |
| --------------- | --------------------------------------------------------- |
| **Override** | Updates records that match by name and adds new ones. |
| **Replace all** | Clears the existing records first, then imports the file. |
| **Ignore** | Keeps existing records and skips duplicates. |
{% hint style="warning" %}
**Replace all** deletes existing records before importing. Export the current data first if you need a backup.
{% endhint %}
#### Importing a new environment
On the **Environments** tab, click **Import** to create a new environment seeded from files. Enter a name for the environment, then upload separate files for **Environment variables** and **Database configs**. A sample template is available for each.
{% hint style="info" %}
Imported database configurations start as **Not verified yet**. Run **Verify** on each connection to confirm connectivity.
{% endhint %}
***
## Tips and best practices
* **Set a default environment early.** The default environment is used whenever no other environment is selected, so configure it before your first run.
* **Use secret variable types for credentials.** Store credentials, API keys, and tokens as Password or Vault environment variables, or Password global variables, and keep them out of screenshots and examples.
* **Keep profile structure stable, vary the values.** Because a profile's columns are shared across environments, design the column set once and let each environment supply its own rows. Avoid one-off columns that only apply to a single environment.
* **Link only the profiles a test needs.** Only profiles linked to an environment appear in that environment's step picker, so linking selectively keeps the picker focused.
* **Tag global variables.** As the global variable list grows, tags make it fast to find related variables with the tag filter.
## Frequently asked questions and troubleshooting
**A variable or column name doesn't save and shows a validation error** The name must start with a letter or underscore, contain only letters, numbers, and underscores, and must not match a reserved keyword such as `os`, `path`, or `get`. See [Variable naming rules](/web-testing/test-data-management.md#variable-naming-rules) for details.
**A test data profile doesn't appear in the step picker** The profile must be linked to the environment the test case runs against. Open the environment's **Data profiles** sub-tab and link the profile, or open the profile and assign it to the environment.
**A profile shows a "master data (deprecated)" tab with read-only rows** These are legacy rows from before per-environment data. Assign the profile to an environment to create editable, per-environment rows.
**Can't delete an environment** You can't delete the default environment. Promote another environment to default first, then delete the original.
**A global variable can't be saved because the name already exists** Global variable names must be unique across the entire workspace. Choose a different name, or check whether the value belongs in an environment variable instead.
What is the difference between an environment variable and a test data profile?
An environment variable is a single deployment-specific value, such as a base URL or API host. A test data profile is a reusable table of columns and rows, such as several registration users. Think of the environment as *where* the test runs and the profile as *what data* the test uses.
Can one profile have different values in different environments?
Yes. The profile's column structure is shared, but each assigned environment stores independent row values. This lets the same test logic use staging-safe data in staging and a different approved data set elsewhere.
Why is my test data profile missing from the test picker?
The profile must be assigned to the environment selected for the test. Open the profile and select **Assign to more environments**, or open the environment's **Data profiles** tab and link the profile.
What happens when I delete an environment or profile?
Deleting an environment permanently removes its variables, database configurations, and profile links; it does not delete the profiles themselves. Deleting a profile removes the profile and its environment links. Review the confirmation dialog and affected-link count before proceeding, and export a backup when recovery may be required.
## Related pages
* [Test Data Management](/web-testing/test-data-management.md) — variable reference syntax and data-driven testing patterns
* [Importing and Exporting Data](/web-testing/importing-and-exporting-data.md) — move data in and out with JSON or Excel
* [Configuring Environments](/execution/environments.md)
* [Database Steps](/web-testing/database-steps.md)
* [Tutorial: Data-Driven Testing](/web-testing/data-driven-testing-tutorial.md)
* [Running Tests](/execution/running-tests.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://learning.contextqa.com/web-testing/environment-data-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.