1. Docs
  2. Resources
  3. Data Source
  4. 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.

9 min read Updated CustomersAdmins

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, _TEST or _PRP variants 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

  1. Click New key; the new key opens in the side panel.
  2. Type the Key name and pick a Folder.
  3. Choose Value comes from and fill the value or pick the cell or query.
  4. Add a Description and click Save.
  5. Use the key in a step as {{ds:yourKey}}.

Create a key#

  1. Open Variables

    Go to Data SourceVariables.

  2. 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_244 and opens it in the side panel, with the Key field selected.

  3. 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.”

  4. 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.

  5. 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#

FieldWhat it does
KeyThe name steps use. No spaces. Required: Save stays disabled while it is empty.
FolderMoves the key to another folder at once. This is not part of Save.
Value comes fromTyped value, Dataset cell or DB query. See below.
Default valueThe 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.
EncryptStores the value encrypted. Only for typed values. See Encrypt a value.
DescriptionWhat the key is for. The AI also reads it.
Connected Actions ListThe actions that use this key. See Connected actions.
Created by / Updated byWho 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.

OptionThe run getsUse it for
Typed valueThe text in Default value, or the environment variant’s value. An empty value gives an empty text.Fixed test data, URLs, secrets.
Dataset cellOne cell of a dataset, read when the step runs.Values that already live in a spreadsheet.
DB queryThe 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#

  1. Choose Dataset cell

    In Value comes from, click Dataset cell. The dialog Select dataset cell opens: “Open with View and click a cell.”

  2. 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.”

  3. Click the cell

    The dialog closes and the value field shows “Dataset linked - {{excel:users_email_2}}”: dataset users, column email, row 2.

  4. 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.

  1. Choose DB query

    In Value comes from, click DB query. The DB Request dialog opens.

  2. Fill the request

    Name (for example “Newest order number”), Configuration (the DB connection) and SQL Query.

    Example · the key returns one order number
    SELECT order_no FROM orders WHERE status = 'NEW' ORDER BY created_at DESC
  3. Save 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.

KeyValueEnvironment column
apiBasehttps://dev.shop.example.com/apiDefault + TEST, PRP chips
apiBase_TESThttps://test.shop.example.com/apiTEST chip + apiBase
apiBase_PRPhttps://shop.example.com/apiPRP chip + apiBase
What a step that uses {{ds:apiBase}} gets
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, _TEST or _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 users uses users_TEST when 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.

  1. Click Add

    In the Connected Actions List, click Add (“You can connect actions to the Data Source”).

  2. Pick actions

    Search with Search Actions and add one or more actions from the Action List.

  3. 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
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc, smarttest-be 633c2a03, smarttest-testsuite (runner)