If your team uses change validation, the mabl policy file, .mabl/policy.yaml, decides which tests mabl runs when a code change reaches each stage of your workflow, and which failures block the change. This article shows how to add a policy file to your repository and make the most common changes to it. For every setting, with its default, rules, and limits, see the policy file reference on GitHub.
A policy file is required for change validation because it names the application, environment, and plans mabl uses. You don't need one to run test impact analysis from your coding agent or as a step in your CI pipeline.
Early access
Change validation is in early access for accounts with generative AI features. Pricing and packaging are subject to change.
Add a policy file
-
In your repository, create
.mabl/policy.yamlwith this starter policy:version: 1 suites: smoke: plan_labels: [smoke] regression: plan_labels: [regression] impacted: include: suites: [smoke, regression] exclude: test_labels: [quarantine] trusted: test_labels: [safe-to-run] logins_from: [smoke, regression] applications: web: mabl_application: '[application-id]' target: url: 'https://pr-{sha7}.preview.example.com' environment: '[environment-id]' credentials: '[credentials-id]' stages: pull_request: checks: - kind: impacted merge_queue: checks: - kind: suite suite: smoke must_pass: true - kind: impacted must_pass: true waiver: {label: skip-impacted-tests} -
Replace each value in square brackets with the ID from your workspace, and replace the URL and the plan and test labels with your own. Keep
{sha7}in the URL as written, because mabl fills it in with the short commit SHA. To find the IDs, see mabl resource IDs. -
Check the file with the latest version of the mabl CLI. From the repository root, run
mabl policy resolve. The command lists any errors with the line each one is on. -
Merge the file into the branch your pull requests target. A change to the policy applies to pull requests only after it merges, so an author can't loosen the rules in their own pull request.
The starter policy validates one application, web, at two stages:
- On each pull request, mabl runs the impacted tests against the pull request's preview deployment and reports the results without blocking it.
- Each merge queue entry must pass the smoke suite and the impacted tests.
The stage names are your own. mabl runs a stage when your pipeline asks for it by name.
Common changes
Make a check block a change. A failed check is a warning until you add must_pass: true to it. Start with warnings, then require the checks you trust.
Let one pull request through. Give a check a waiver label, as the starter policy does with skip-impacted-tests. A pull request that carries the label passes that check, whatever its tests do.
Run more of the impacted tests. mabl runs an impacted test only when it's sure the test doesn't write data. If an analysis finds impacted tests but few of them run, add a label to the tests you're comfortable running on any pull request, and list that label under trusted, as the starter policy does with safe-to-run. See Trusted labels.
Test without preview deployments. Leave url out, and tests run at the environment's own URL. To test a change after it merges and deploys to a shared environment, add a stage with scope: revision. See the shared staging example.
Validate more than one application. Add each application under applications, and give each one trigger_paths so a pull request runs only the checks of the applications it touches. See the example for a repository with more than one application.
Keep tests on mabl branches. When a pull request has a mabl branch, the stage runs the tests on that branch, so the tests you updated for the change run in their updated form. To have mabl merge that branch into master when the pull request merges, set merge_mabl_branches: true. See mabl branches.