Exploratory testing¶
Sessions are managed in the Web client. Windows preserves their data but does not yet provide a dedicated session interface.
An exploratory session records a focused investigation: what do you want to learn, what did you observe and which questions remain? No predefined test cases are required. Each session belongs to a test plan, which may be empty. It does not create an ordinary test run or change pass rates or release readiness.
Run a one-off investigation¶
For a question such as “Does the shopping cart keep its contents after a refresh?”, a short session is enough. Select an existing test plan, enter the question as the charter and start the session. Record the initial state as a Note. If the cart empties, add a Finding and attach the screenshot to that entry. Finish with a brief conclusion. The note, image and finding stay together in the session log.
If the checks are already known and testers will repeat the same list, use a quick test case. If you discover a check worth repeating during the investigation, use Test case conversion on that finding later.
Prepare a session¶
- Open Exploratory testing in the project work area.
- Choose Plan a session. In the dialog, select a test plan on which you have write access.
- Enter a meaningful title, a charter and a timebox between 1 and 480 minutes.
- Choose Create session. The session opens on its own detail page. You can correct its title, charter and timebox before starting it.
Cancel or the close icon closes the dialog. Escape and a click outside the dialog do not close it. If you changed any fields, the application asks for confirmation; Cancel in that confirmation returns to the dialog. Your entries remain available when you reopen it until you leave or reload the page. After a validation error, the dialog reopens with the error message and your entries.
A useful charter states the goal and boundaries, for example: “Explore checkout when the connection is interrupted. Look for duplicate orders and understandable feedback.” It is not a mandatory sequence of test steps.
Start, pause and resume¶
Start begins the session. Pause stops active timing; Resume starts another active interval. The server calculates the duration. The timebox is guidance and does not end the session automatically.
Important: Closing the browser does not pause a running session. Explicitly pause before a longer interruption. The duration supports session planning; it is not a billing record.
Record observations and evidence¶
During a running or paused session, add entries:
| Type | Purpose |
|---|---|
| Note | Actions taken, observations or an interim summary |
| Question | An unresolved assumption or a question to follow up |
| Finding | An observation that merits further investigation |
For a finding, describe the initial conditions, action and observed behavior. A finding is an observation, not a confirmed software defect. The application does not create an external issue automatically.
An entry can include a screenshot or file. Project file-type and size restrictions still apply, together with the displayed session limits. Files are saved with their entry and are available only to authorized readers. Executable or active content is not embedded as a page. HTML-like journal content remains plain text.
Saved entries cannot be overwritten. Add another note to correct a previous entry so that order, author and time remain traceable. If another window has changed the session, reload it instead of overwriting the newer state.
Complete a session¶
Choose Complete and enter a summary: what was investigated, which findings are supported and what remains open? After explicit confirmation, the completed session is read-only. Create a new session to continue the investigation.
Completion is neither a passing test result nor a release approval. You can subsequently create regular test cases yourself for repeatable checks; this does not happen automatically.
Turn a finding into a test case¶
A finding can become a normal test case in the test library, including findings from paused or completed sessions. Notes and questions cannot be converted.
- Open the finding and choose Test case conversion.
- Select a test unit in which you may create test cases.
- Review the title and suggested description. Write the prerequisites, test steps and expected results yourself. The observed problem is not automatically treated as the expected result.
- Choose Review conversion. Check the preview, then confirm with Create test case.
Existing evidence is copied into an independent attachment. The new test case and its first version contain the approved text and file. The original session, finding and evidence remain unchanged. You can then edit the ordinary test case in either Web or Windows. Its Web view shows its origin and links to the finding when you still have read access. Otherwise, only a general origin notice is shown.
Each finding creates at most one test case. Repeating the operation links to the existing case if you can still read it. Later edits or deletion do not automatically create a replacement. A failed conversion can be retried with the same request and must not leave a partial test case.
You need read access to the source plan and permission to create cases in the destination test unit. You do not have to own the session. Conversion does not edit a completed session. Deleting the source later does not delete the independent target case or its copied attachment.
Permissions and retention¶
Test-plan read permissions cover the session, journal and files. The creator with current plan write access, or an administrator, may make changes. Being a project manager alone does not grant permission to change somebody else's session. Disabled users or revoked plan permissions also lose access through previously known links.
Deleting the parent test plan also removes its exploratory sessions and evidence. Project backups and conversion between VistaDB and SQL Server preserve session data and files. Back up the project before an intentional deletion.
MCP and REST¶
The APIs use the same domain rules as the Web interface. Read operations provide sessions, journals and authorized evidence. Writes use the existing preview and explicit prepare/commit confirmation. Creator and author come from the authenticated user context; API calls cannot impersonate another tester.
Read tools are ztm_exploratory_sessions_list (optional testPlanId, limit from 1 to 100), ztm_exploratory_session_read (sessionId) and ztm_exploratory_evidence_read (sessionId, entryId). Writes use ztm_project_action_prepare and ztm_project_action_commit with project.exploratory-testing.create, .edit-planned, .transition or .add-entry. Every command requires a requestId; updates additionally require expectedRevision. Transitions are Start, Pause, Resume, Complete; entry kinds are Note, Question, Finding. Optional evidence contains fileName and contentBase64, limited to 512 KiB for API writes because of the MCP request limit. Web uploads allow up to 8 MiB; stricter project limits apply to both. Existing evidence can be read completely up to the 8 MiB storage limit. REST exposes tools at /api/v1/operations/{operationId}. Changes must specify the matching session revision; identical repeated requests are not executed twice.
Limits are 8 MiB per file, 64 MiB of evidence per session, and 1000 journal entries. Completing a session remains possible after the entry limit is reached.
Example arguments for preparing a session (replace the test-plan ID and unique request ID):
{
"capabilityId": "project.exploratory-testing.create",
"idempotencyKey": "exploratory-create-unique-request",
"arguments": {
"requestId": "b0a6608b-f4bd-4c6a-8b8b-efec40adee83",
"testPlanId": 42,
"title": "Investigate checkout",
"charter": "Explore interrupted connections and retained input.",
"timeboxMinutes": 30
}
}
Send these arguments to ztm_project_action_prepare. Review the preview, then pass its previewToken with the same capabilityId to ztm_project_action_commit. This requires a project API key with the matching write scope and current plan permissions. Preparing alone does not create a session.
Finding conversion through the APIs¶
ztm_exploratory_finding_conversion_context returns the readable finding, its conversion status and a page of permitted destination test units. It requires sessionId and entryId; query, skip, take and selectedTargetTestUnitId are optional. The latter returns the authorized label of a previously selected test unit independently of the current result page. ztm_exploratory_finding_conversion_origin reads the origin of a readable case using testCaseId. Source identifiers and the session title are returned only while source read permissions remain valid.
The write capability project.exploratory-testing.convert-finding also uses prepare and commit. Its arguments are sessionId, entryId, requestId, targetTestUnitId, title, description, prerequisites, steps and expectedResults. Titles are limited to 500 characters and each of the four text fields to 8000 characters. This operation does not accept a session revision: its preview binds the specific finding and destination context. Changing the reviewed draft requires a new preview.
The API copies the existing stored evidence itself. Its 8 MiB storage limit, or a stricter project limit, therefore applies; the 512 KiB limit for new API uploads does not apply here. An identical repeated request does not modify an already created case. An unreadable or deleted destination is reported without hidden IDs or titles. Demo protection, write scope and current source/destination permissions still apply.
Open from Windows¶
In the Windows project tree, right-click a test plan and choose Open exploratory testing on the web. The Web page uses that test plan. Opening the page does not create a session.
Your authenticated Windows session signs you in automatically. Only if the handoff fails does the sign-in page appear; the destination is retained.