QA journey tools
Tools for a project’s Agentic QA journeys: the regression steps a QA run drives in a real browser. A
QA journey is not an accessibility journey, and its id (qaj_…) is not a journey id.
list_qa_journeys returns the ids that get_qa_journey, update_qa_journey,
set_qa_journey_persona, delete_qa_journey and start_cloud_qa_audit take. Each id argument also accepts the journey’s
base64 QaJourney global id.
import_qa_journeys is the only way to create a QA journey; there is no separate create tool.
update_qa_journey changes one journey’s name, entry and steps in place, so it keeps its id, its
runs and their QA Findings. set_qa_journey_persona changes only who a journey signs in as. The
organization’s plan caps how many QA journeys a project can hold, and an import past that cap is
refused.
list_qa_journeys
Section titled “list_qa_journeys”List a project’s QA journeys, newest first.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
first | number | no | How many journeys to return, 1 to 100. Default 20. |
after | string | no | pageInfo.endCursor from the previous call, to load the next page. |
Returns: journeys, totalCount and pageInfo (hasNextPage, endCursor). Each journey has
its id (qaj_…), name, startPath (the start page’s path on the project’s site), stepCount,
locale (null when not set) and persona: the id and name of the persona it signs in as, or
null for a public journey. An unknown project is an error block.
get_qa_journey
Section titled “get_qa_journey”Get one QA journey with its steps.
| Name | Type | Required | Notes |
|---|---|---|---|
qa_journey_id | string | yes | A qaj_… id from list_qa_journeys. |
Returns: the journey’s id, name, startPath, locale, persona (id and name, or
null for a public journey), viewport (width and height, or null) and steps in order,
each with its instruction and expectedResult (null for a step that is performed but not
judged). A missing journey or one outside the caller’s organization returns null.
import_qa_journeys
Section titled “import_qa_journeys”Import QA journeys into a project.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
journeys | object[] | yes | The journey file shape b8e qa journeys import reads. |
persona_id | string | no | A persona id from list_personas. Every journey in the call signs in as it. |
Each journey has a name, exactly one of startUrl (a URL on the project’s site) or startPath,
an optional locale, viewport and sourceKey, and at least one step with an instruction and an
optional expectedResult. A journey whose sourceKey matches one already in the project updates
that journey.
persona_id belongs to the call, not to the file: the journey file stays the portable shape the CLI
imports, and a persona id only means something inside one project. Without it the new journeys are
public, and a journey a sourceKey updates keeps its persona. Import journeys that need different
personas in separate calls, or change one afterwards with set_qa_journey_persona.
Returns: created, each imported journey’s id and name. The import is all or nothing: an
error block naming kontrol’s refusal code and reason creates nothing. The codes are
qa_journey_file_invalid, qa_start_url_off_site (a start URL not on the project’s site) and
qa_journey_limit_reached (the plan’s QA journey cap). A persona kontrol refuses is an error block
carrying its message; see Persona refusals. A file outside the shape is refused
before anything is sent.
update_qa_journey
Section titled “update_qa_journey”Change a QA journey’s name, entry and steps in place. Its id, its persona and its past runs stay.
| Name | Type | Required | Notes |
|---|---|---|---|
qa_journey_id | string | yes | A qaj_… id from list_qa_journeys. |
name | string | yes | The journey’s name. |
entry | object | yes | Where the journey starts. See below. |
steps | object[] | yes | Every step in order, each with an instruction and an optional expectedResult. Replaces the stored steps. |
entry is a web journey’s {kind: "web_path", path, viewport?}, with path beginning with /, or
an app journey’s {kind: "launch"}, {kind: "deep_link", url} or {kind: "tap_path", taps}. The
entry and steps are checked against the same schemas import_qa_journeys checks a journey file
against, and an argument outside them is an error block with nothing sent to kontrol.
The tool sends no persona, so the journey keeps the one it signs in as. Change that with
set_qa_journey_persona.
Returns: the updated journey, in the shape get_qa_journey returns. A refusal from kontrol is
an error block carrying its message, and nothing is saved:
| Refusal | When |
|---|---|
not_found | The project has no QA journey with that id. |
entry_platform_mismatch | The project’s platform cannot run the entry: an app entry on a web project, or a web path on an android or ios project. |
persona_not_in_project, persona_on_app_journey | the persona check runs only when a persona is sent, and this tool sends none, so it never returns them; they come from set_qa_journey_persona and from import_qa_journeys with a persona_id; see Persona refusals. |
set_qa_journey_persona
Section titled “set_qa_journey_persona”Change who a QA journey signs in as. Its name, entry and steps stay as they are.
| Name | Type | Required | Notes |
|---|---|---|---|
qa_journey_id | string | yes | A qaj_… id from list_qa_journeys. |
persona_id | string | no | A persona id from list_personas. The journey signs in as it. |
clear_persona | boolean | no | true makes the journey public: it signs in as no one. |
Pass exactly one of persona_id and clear_persona: true. Neither, or both, is an error block, and
nothing is sent to kontrol.
Returns: the journey’s id, name and persona (id and name, or null). A persona kontrol
refuses is an error block; see Persona refusals.
delete_qa_journey
Section titled “delete_qa_journey”Delete a QA journey.
| Name | Type | Required | Notes |
|---|---|---|---|
qa_journey_id | string | yes | A qaj_… id from list_qa_journeys. |
Returns: a confirmation sentence naming the deleted id. The journey’s past runs are kept. An id the project does not have is an error block.
Persona refusals
Section titled “Persona refusals”kontrol refuses a persona the journey cannot sign in as, and the tool answers with an error block carrying kontrol’s message. Nothing is saved.
| Refusal | Message |
|---|---|
persona_not_in_project | That persona isn’t in this project. |
persona_on_app_journey | An app journey can’t run as a persona. Personas sign in to a web site. |