Test data matrix¶
The guided matrix is available in the Web client. Its results are ordinary test case variants that can also be used in Windows.
Use the test data matrix to create selected combinations of existing variant values for a library test case. For example, two browsers, two roles and two datasets produce eight combinations:
| Dimension | Selected values |
|---|---|
| Browser | Chromium, Firefox |
| Role | Customer, Administrator |
| Dataset | Standard, Special characters |
A “dataset” in this combination table is a named variant value. In addition, structured test data sets provide columns and rows whose values can be explicitly applied to test text. Test environments remain separate: they group entire test runs.
Prerequisites¶
The project must use test variants. The required dimensions and values must already exist in variant management. Adding combinations requires write access to the library test case. Read access allows you to inspect the preview; adding variants still requires write access.
Select and add combinations¶
- Open the required case in the Web test case library and choose Test data matrix in the case header. The entry is also available in the context menu of the selected case in the library tree.
- Select the required values in each dimension. A dimension participates only when you select at least one of its values.
- Choose Preview combinations. The application combines the selected values from every participating dimension. It uses actual values only; it does not add an extra empty option.
- Review which combinations already exist as test case variants. Select only the missing combinations you want to add.
- Choose Add selected combinations and confirm the addition. Then open the ordinary test case variants and review or complete their test content.
Existing variants retain their content. Existing combinations are not created again. The preview contains at most 200 combinations; a lower configured project variant limit also restricts the preview. The total number of existing and newly added variants must remain within the applicable limit. Reduce your selection if the application reports a limit.
If the case or its variants change between preview and application, the outdated preview is rejected. Generate a new preview and review your selection again.
Content and planning¶
New combinations use the existing variant model. Review inherited test steps and expected results before planning these variants. For Quick test cases, rows from the primary variant are copied only when the corresponding project setting is enabled. The matrix does not introduce an additional version history for Quick test cases.
Previously planned cases, running test runs and results are not updated automatically. Include the new variants in your next explicit planning step. The matrix does not start a run or create a test result.
MCP and REST¶
ztm_project_test_data_matrix reads the available selection using operation: "context" and testCaseId. Use operation: "preview", the same testCaseId and valueIds to obtain a preview. Use the IDs of existing values returned by the context.
Changes use ztm_project_action_prepare and ztm_project_action_commit with capability project.test-data-matrix.apply. Arguments are testCaseId, selectedCombinations (an array of arrays containing value IDs) and expectedFingerprint from the current preview. Submit only the missing combinations deliberately selected for addition. Preparing alone saves nothing; review and confirm the preview before committing.
REST exposes the same operations at /api/v1/operations/{operationId}. Both APIs apply the same permissions, limits and conflict checks as the Web client. A project API key needs the corresponding read or write scopes; a write scope does not override test case permissions.
Structured test data sets¶
Open Test data sets from the Test data matrix. To apply data to a test case, first select its test variant and Select test data. Administration is in the Web client; applied text can also be used in Windows.
- Create and name a data set and assign its owning test unit. That unit's permissions determine who can read or edit the data.
- Define one column key per line. Keys start with a letter and contain only ASCII letters, digits and underscores, for example
AccountorExpectedMessage. - Add rows, enter values and select Save data set. Limits are 30 columns, 1,000 rows, 32,767 characters per cell and 2 MiB of total data content. Empty cells are valid values.
The grid displays compact values. Click a cell to edit; Enter inserts a line break and Tab moves on. Save data set also commits the active cell editor. Sorting and paging change neither row IDs nor the stored order. The remove-row action remains visible on the right and asks for confirmation. Values such as 0007 remain text.
Data sets are ordinary project content, not a secret store. Use synthetic values rather than production passwords or personal data.
XLSX exchange¶
Export XLSX creates a workbook with one worksheet. Its first column, _RowId, contains stable row IDs; remaining columns contain the column keys. Retain IDs for existing rows and leave them blank for new rows. Headers must be nonempty and unique.
Preview XLSX import loads the rows into the editor. Only Save data set replaces the stored content. Omitted existing rows are removed, but bound rows cannot be removed. Saving is rejected if the data set changed after preview.
Formulas, macros and external links are rejected. Paste values instead. Exports write literal text, preserving leading zeros, multiline values and values starting with =. Uploads are limited to 4 MiB; unpacked size and data-content limits are checked as well.
Applying values to test text¶
Use {{data:Account}} in test text to refer to the Account column. For the target variant, select a data set and row and choose Preview replacement. Unknown columns and unsafe token positions, such as HTML addresses, prevent application. Values are never executed as HTML or recursively interpreted as tokens.
Apply these values stores the reviewed text and values on the variant, retaining its original templates for a later explicit reapplication. Nonprimary variants can use their own data even when their original text is inherited. Reusable step sections and Quick-test cells are included.
Later data changes do not update test text automatically. New planning uses the most recently explicitly applied variant content. Existing test runs retain their stored content. Remove binding, retain text removes the association while keeping the applied text.
Test-case versioning includes the binding and applied values. Restoring an earlier revision uses its historical content rather than today's data. A data set or row still bound to library variants cannot be deleted.
Open from Windows¶
In the Windows test case library, right-click a saved test case and choose Open test data matrix on the web. The browser preselects that test case; Quick tests are supported too.
Your authenticated Windows session signs you in automatically. Only if the handoff fails does the sign-in page appear; the destination is retained.