- Docs
- Resources
- Data Source
- Variables (keys)
Variables: keys and folders
A key is one named value that test steps read. This page covers creating keys and folders, the three value sources, environment-specific keys, connected actions, and changing or deleting keys without breaking tests.
In short
On this page you can
- Create a key and give it a typed, dataset or database value.
- Group keys in folders and sub folders, and move them by drag and drop.
- Add
_DEV,_TESTor_PRPvariants of a key for one environment. - Connect a key to the actions that use it, so the AI knows the data a page needs.
- Find empty, encrypted and environment-specific keys with the summary cards.
How to use it
- Click New key; the new key opens in the side panel.
- Type the Key name and pick a Folder.
- Choose Value comes from and fill the value or pick the cell or query.
- Add a Description and click Save.
- Use the key in a step as {{ds:yourKey}}.
Create a key#
Open Variables
Go to Data SourceVariables.
Click New key
Click New key at the top for a key at the top level, or New key in a folder’s row menu to create it inside that folder. SmartestQA creates the key with a placeholder name such as
new_key_244and opens it in the side panel, with the Key field selected.Name it
Type the name the steps will use, for example
loginEmail. Spaces are removed as you type. The name must be unique in the project; otherwise you see “This key already exists. Please enter a different name.”Set the value
Leave Value comes from on Typed value and fill Default value. For a password or token, switch on Encrypt first; see Encrypt a value.
Describe and save
Add a Description, for example “Login of the standard test user”, and click Save.
“'loginEmail' updated successfully”. The key appears in its folder, and every step can read it as
{{ds:loginEmail}}.
The key panel#
| Field | What it does |
|---|---|
| Key | The name steps use. No spaces. Required: Save stays disabled while it is empty. |
| Folder | Moves the key to another folder at once. This is not part of Save. |
| Value comes from | Typed value, Dataset cell or DB query. See below. |
| Default value | The value for a typed key. It is the default because environment variants can replace it. For a bound key the field is read-only and shows the binding. |
| Encrypt | Stores the value encrypted. Only for typed values. See Encrypt a value. |
| Description | What the key is for. The AI also reads it. |
| Connected Actions List | The actions that use this key. See Connected actions. |
| Created by / Updated by | Who created and last saved the key, and when. |
The copy and delete icons sit in the panel header. If you close the panel or open another key with unsaved changes, you are asked “Are you sure to exit without saving?” with Exit without saving, Cancel and Save and Exit.
Where a value comes from#
A key has exactly one value source. Pick it under Value comes from; the choice is stored when you click Save.
| Option | The run gets | Use it for |
|---|---|---|
| Typed value | The text in Default value, or the environment variant’s value. An empty value gives an empty text. | Fixed test data, URLs, secrets. |
| Dataset cell | One cell of a dataset, read when the step runs. | Values that already live in a spreadsheet. |
| DB query | The first column of the first row the SQL query returns, read when the step runs. | Values that change in the application, for example the newest order number. |
Read a dataset cell#
Choose Dataset cell
In Value comes from, click Dataset cell. The dialog Select dataset cell opens: “Open with View and click a cell.”
Open the dataset
Find it with Search datasets and click its row. The table opens. Headers cannot be picked here: “Headers aren't selectable; click a cell to pick its value.”
Click the cell
The dialog closes and the value field shows “Dataset linked -
{{excel:users_email_2}}”: datasetusers, columnemail, row 2.Save the key
The key now always returns that cell. Change the cell in the dataset and the key follows.
To remove the link, open the dialog again and click Remove (“Remove the dataset link?”), or switch back to Typed value, then save.
Read a value from a database#
You need a DB connection first.
Choose DB query
In Value comes from, click DB query. The DB Request dialog opens.
Fill the request
Name (for example “Newest order number”), Configuration (the DB connection) and SQL Query.
Example · the key returns one order numberSELECT order_no FROM orders WHERE status = 'NEW' ORDER BY created_at DESCSave the dialog, then the key
The value field shows “DB Connected - connection | query”. Click Save on the key.
“'key' updated successfully”. Each time a step reads the key, the query runs and its first value is used.
The query runs on every read
Any query type is accepted: SELECT, INSERT, UPDATE, DELETE, DDL and stored procedures. The dialog warns about changes that are committed, about UPDATE or DELETE without WHERE, and about DROP or TRUNCATE. For a key, use a SELECT: a key that changes data every time a step reads it is hard to reason about. If the query returns no rows, the step fails with “Could not resolve DB data source 'key': query returned no rows (0)”.
SELECT rules: the query must be in “SELECT … FROM …” form, list at least one column, and must not use * (“Asterisk (*) is not allowed. Please specify explicit column names.”). Put uppercase or reserved table and column names in double quotes: SELECT username FROM "user" WHERE id = 1.
One source at a time#
- A key bound to a database cannot be linked to a dataset: “This data source is bound to a DB. Remove the DB binding first to link a dataset.” The reverse gives “This data source is linked to a dataset. Remove the dataset link first to bind a DB.”
- A bound key is never encrypted. Choosing Dataset cell or DB query switches Encrypt off.
- A DB-bound key cannot be copied: “This datasource is associated with a DB object. Copy cannot be performed.”
Environment-specific keys#
When a value differs per environment, keep one key per environment. Steps and pipelines always reference the name without the suffix.
| Key | Value | Environment column |
|---|---|---|
apiBase | https://dev.shop.example.com/api | Default + TEST, PRP chips |
apiBase_TEST | https://test.shop.example.com/api | TEST chip + apiBase |
apiBase_PRP | https://shop.example.com/api | PRP chip + apiBase |
Run in DEV → apiBase (no apiBase_DEV exists, so the default)
Run in TEST → apiBase_TEST
Run in PRP → apiBase_PRP- The suffix is exactly
_DEV,_TESTor_PRP, upper case, at the end. Other underscores in the name are fine:checkout_user_TEST. - A step that names a variant directly,
{{ds:apiBase_TEST}}, always gets that key, whatever the environment. - The same rule applies to datasets: a TEST run that reads dataset
usersusesusers_TESTwhen it exists. - The environment is the one the run uses (DEV, TEST or PRP), the same one that picks the start page URL.
- Send on the API Requests page and other previews on the screen use the default value, not a variant.
The Environment column shows All (“Used in every environment”) for a key without variants, Default plus chips for a key that has variants, and the environment chip for a variant. The Environment-specific card lists both.
Folders#
- Create: New folder at the top, or New sub folder in a folder’s row menu. Name it in the dialog (Folder name).
- Rename: folder menu › Rename.
- Collapse: click the folder header. Keys at the top level have no header: Top level (no folder).
- Delete: folder menu › Delete. “The folder, its sub folders and every key in them are deleted. Test steps that use these keys can no longer read them.” A folder that is not empty can only be deleted by an Admin.
Folders are for people. A key’s folder does not change its name in steps: {{ds:loginEmail}} works wherever the key sits.
Connected actions#
The Connected Actions List on the right of the key panel records which actions use the key, for example action Type Email on page login for loginEmail.
Click Add
In the Connected Actions List, click Add (“You can connect actions to the Data Source”).
Pick actions
Search with Search Actions and add one or more actions from the Action List.
Save the key
The Actions column of the key shows how many actions are connected.
What it changes: the App Map tells the AI which data each page needs (key name, kind, description and whether it is encrypted, never the value), so generated tests use your keys. Deleting a connected action shows the key under “Data Sources Using Action”; see Deleting actions. Connecting an action does not fill its steps: a step still needs {{ds:key}} in its value.
Find keys#
- Summary cards double as filters: Keys, No value, Environment-specific, Encrypted. Click one to filter, click it again to show all. How they count: Summary cards.
- Search: Search key or description matches any part of the key or description.
- Kind column: empty for a plain key, otherwise Encrypted, DB or Dataset.
- Default value column: No value in amber for a plain key without a value, “•••••••• set” or “no value” for an encrypted key, “DB Connected” for a DB-bound key, the cell reference for a dataset key.
Copy, move and delete#
Copy#
Row menu › Copy, or the copy icon in the panel. The copy lands in the same folder as loginEmail_copy (then _copy2, _copy3…), with the same value and description, no connected actions and no dataset link. It opens in the panel so you can rename it. An encrypted key is copied as a plain key without a value: type the secret again and switch on Encrypt.
Move#
Drag a key (or several checked keys) onto a folder, or onto the bar “Drop here to move to the top level”. You can also use row menu › Move to folder, the Folder field in the panel, or check several keys and click Move to folder. Moving never changes how steps reference the key.
Delete#
- Only an Admin can delete a key. Others get “Failed to delete data source. Please try again.”
- Row menu › Delete, the delete icon in the panel, or check keys and click Delete. The dialog says “Test steps that use these keys can no longer read them. This cannot be undone.”
- Steps that reference a deleted key keep the reference, so they lose their value at run time. Search the tests for
{{ds:key}}before you delete, or rename the key instead.
Renaming a key breaks its references too
Steps store the key’s name, not its id. After a rename, update every step that still uses the previous name. Safer: create the new key, switch the tests to it, then delete the old one.
If something goes wrong#
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai