Run Tests on Save With a Hook

A hook is an automated trigger that runs an agent prompt or a shell command when something happens in your project. Point one at file saves under your source folder and Kiro runs the matching tests without you asking.

When to use this

Use this when a fast test command exists and you want the feedback loop closed while you work. It suits unit tests for one module. It does not suit a full integration suite, because a slow action on a frequent trigger is the fastest way to make a team disable hooks entirely.

Steps

1. Confirm your test command runs quickly on its own. Try it in the terminal first, scoped to one folder, for example pytest tests/services/ -x.

2. Open the hooks section of the Kiro panel, or find the hook commands in the Command Palette.

3. Create a new hook. Kiro accepts a natural-language description, and the IDE also offers a guided form (added in v1.0.242). Describe the trigger and the action in one sentence:

   When a file under src/services/ is saved, run the tests for that
   module and summarise any failures. Do not change any files.

4. Choose the trigger type when the form asks. For this recipe that is file save. The other trigger types are file create, file delete, prompt submission, agent turn complete, before and after a tool call, before and after a spec task, and manual on demand.

5. Narrow the file pattern to a single area. src/services/** is a useful hook. A pattern that matches the whole repository is not.

6. Save the hook. Kiro writes the configuration into .kiro/hooks/ in your workspace. Commit the folder so the team shares it. To reuse the hook in every project, create it as a global hook in ~/.kiro/hooks/ instead.

7. Decide whether the hook may run commands. The shell capability is checked against your permission rules like any other agent action, so a hook that runs tests needs shell approval. See Set up permissions.yaml.

Check it worked

Open a file under your scoped folder, make a trivial change, and save it. The hook should fire and the run should appear in chat within seconds. Then break a test on purpose and save again. You should get the failure summarised rather than a wall of raw output. The CLI configuration panel (v2.21.0) lists hooks alongside your other configuration if you want to confirm the hook is registered.

Common problems

• The hook never fires. The file pattern is usually wrong. Check that it is relative to the workspace root and that the file you saved really matches.
• The hook fires constantly. Your pattern is too wide, or a formatter rewrites files on save and re-triggers it. Narrow the pattern.
• A loop starts. The hook writes a file that matches its own trigger. Move the output, or change the action so it only reports.
• Every run asks for approval. Command execution is permission-checked. Add an allow rule for the exact command instead of trusting everything.
• The team disables it. The action is too heavy. Run one module’s tests, not the whole suite.

Related

• Hooks explains every trigger type.
• Keep docs in sync with a hook is the natural second hook.
• Advanced Tutorial puts both hooks inside a full team workflow.