Skip to content

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 a project’s QA journeys, newest first.

NameTypeRequiredNotes
project_idstringyes
firstnumbernoHow many journeys to return, 1 to 100. Default 20.
afterstringnopageInfo.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 one QA journey with its steps.

NameTypeRequiredNotes
qa_journey_idstringyesA 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 into a project.

NameTypeRequiredNotes
project_idstringyes
journeysobject[]yesThe journey file shape b8e qa journeys import reads.
persona_idstringnoA 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.

Change a QA journey’s name, entry and steps in place. Its id, its persona and its past runs stay.

NameTypeRequiredNotes
qa_journey_idstringyesA qaj_… id from list_qa_journeys.
namestringyesThe journey’s name.
entryobjectyesWhere the journey starts. See below.
stepsobject[]yesEvery 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:

RefusalWhen
not_foundThe project has no QA journey with that id.
entry_platform_mismatchThe 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_journeythe 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.

Change who a QA journey signs in as. Its name, entry and steps stay as they are.

NameTypeRequiredNotes
qa_journey_idstringyesA qaj_… id from list_qa_journeys.
persona_idstringnoA persona id from list_personas. The journey signs in as it.
clear_personabooleannotrue 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 a QA journey.

NameTypeRequiredNotes
qa_journey_idstringyesA 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.

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.

RefusalMessage
persona_not_in_projectThat persona isn’t in this project.
persona_on_app_journeyAn app journey can’t run as a persona. Personas sign in to a web site.