- Docs
- AI
- MCP & AI assistants
- Safe changes
Safe changes: propose, then apply
An assistant never changes a record in one step. It first shows you the change as a diff; only when you approve does it write exactly that. Some actions also need your click in a dialog.
In short
On this page you can
- See every proposed change as a diff with its impact before anything is written.
- Approve a change in the chat, or ask the assistant to amend the draft.
- Confirm irreversible actions (removals, stopping runs, bulk sync) with a click.
- Keep passwords and tokens out of the chat with empty data source keys.
How to use it
- Ask for the change in plain words.
- Read the diff, the impact lines and any hints the assistant shows.
- Say yes; the assistant applies that preview and nothing else.
- For removals, confirm the dialog (Admins only).
- Check the result in SmartestQA; admins see it in the audit log.
How a change is approved#
The assistant drafts
From your request it builds a draft: for example two modules, a main requirement with three sub-requirements, a scenario plan or new locators.
It proposes
smartest_proposechecks the draft against SmartestQA’s rules and your project, and returns a diff (what will be added, changed or removed), impact lines (what else it touches), hints and a preview id. It writes nothing.You read and decide
The assistant shows you the diff. Say yes, ask for a change (it amends the draft and proposes again), or say no.
It applies
smartest_applygets only the preview id and writes exactly what the diff showed. If the records changed since the preview, it refuses and proposes again.The records appear in SmartestQA. If the write stopped halfway (for example a connection error), the same preview finishes what is left.
Proposed for project Web Shop:
+ MAIN Checkout module: Orders
+ SUB Pay with a saved card under: Checkout
+ SUB Card is declined under: Checkout
Impact: 0 existing records change.
Apply this?The same two-step rule applies to locators (smartest_action_write) and auto-heal decisions (smartest_heal): first a preview, then the write after you agree.
Previews#
| Situation | What happens |
|---|---|
| Applied once already | Refused with STALE_PREVIEW: “this preview was already applied. Nothing was written again”. |
| Records in scope changed since the preview | Refused with STALE_PREVIEW; the assistant proposes again and shows you the new diff. |
| Older than 30 minutes, or the MCP restarted | Refused: “the preview expired (30 minutes)”. Propose again. |
| A quality gate is not met | Refused with HINT_UNMET: “a gate is not met; propose again.” |
| Everything already matches | “Nothing to write: everything already matches.” |
A preview covers only the records it reads. A write in another main requirement does not make your preview stale.
Actions that need your click#
Some actions cannot be undone. For these the MCP server opens a confirmation dialog in your client, and the action runs only if you confirm it there. The assistant cannot click it for you.
| Action | Dialog says, for example |
|---|---|
| Removing records (intent remove) | “Will be permanently removed: … This cannot be undone.” Only an Admin can remove; others get “only an admin can remove records (your role: …); nothing was removed”. |
| Changing a record someone edited in SmartestQA after the MCP | “WARNING: … was edited by someone else after the MCP.” No Admin needed. |
| Stopping a run | “Stop run … ? The running scenario finishes; the rest are skipped and show as FAILED. A stopped run cannot be resumed.” |
| Cancelling a self-hosted runner job that has not started yet, mailing a report | A dialog naming the job or the address. A dry run cannot be stopped. |
| Bulk sync to Jira, Xray or Confluence | “Send every unsynced record of project … ? This can create many issues or pages and cannot be undone.” |
| Running a writing SQL statement on a database | A dialog with the statement. |
- If you decline: “NOT DONE - the user declined the confirmation dialog. Nothing was changed.” The assistant should not try again unless you ask.
- If your client cannot show dialogs: “NOT DONE - this action needs the user's click in a confirmation dialog and this connection cannot show one. Nothing was changed.” Do it in the SmartestQA screen, or from a client that shows dialogs.
- Defects cannot be deleted through MCP; they are closed with a note of what was done.
Other safeguards#
- Your permissions. Every call runs as your SmartestQA user. The assistant reaches only the projects you can reach, and a call you are not allowed to make is refused.
- No guessing the project. Without a project, the first call lists your projects and the assistant must ask which one.
- No passwords. “Never ask for or write a password: credentials are datasource keys with empty values that the user fills in SmartestQA.” Steps and API requests refer to them as
{{ds:key}}. - The right language. Content (requirements, scenarios, steps, notes, documents) is written in the project’s language. A write in another language is refused. If the project has no language set, the assistant asks you and saves it.
- Honest results. A failed call is flagged as an error; the assistant must not report it as done.
- Read-only installs. A local install with
SMARTEST_READONLY=truesees only reading tools. See Update, list or remove. - Traceable. Changes made through MCP appear in ConfigurationLogsAudit logs (Admins) with the source MCP (Claude). Denied attempts are recorded too.
The scenario flow in short#
Writing tests has its own steps, so each scenario is approved twice: once as a plan, once as a green dry run.
Plan
For a sub-requirement, the assistant proposes a scenario plan (
level=scenario): for each scenario the rule it checks, the bug it would catch, its proof, and a step outline, plus any new actions and data keys. You approve it withsmartest_apply.Write and dry-run
smartest_write_casewrites the steps and runs them once, on the server or on your online agent.Fix or decide
Red: it names the failed step and the likely cause, fixes and runs again. After three red runs the scenario is BLOCKED and the assistant asks you how to go on.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai