Run Performance Tests

In brief: Run-perf-tests is script-first k6 execution—related journeys for a PR, or prior-SHA-to-cut-SHA for a named release, with baseline comparison on matching dimensions and optional nested authoring when the cut is uncovered.

:::tip Authoritative product docs Performance Testing · viewing results · when to use which workflow. This page is the agent playbook. :::

Run Performance Tests (workflow-id: run-perf-tests) is the execution analog of Run smart smoke—for k6. Script-first: CI and local wrappers work without an agent. Soft-gate PERFORMANCE_TESTING. Does not run k6 load/volume inside /testchimp test. Run QA does write plans/smart-smoke/<branch>/related-perf-tests.json when k6/journeys exists so CI can later k6/scripts/run.sh --impacted.

When to use

• After a PR, to run related journeys (not the entire k6/ tree).
• When a release is cut, to run the release git range and stamp ingest with that version.
• In CI via k6/scripts/run.sh (optional --impacted once related-perf-tests.json is committed) with the same env vars the playbook uses. Merge-gate jobs typically use K6_PROFILE=smoke and skip when the related-perf file is missing (do not fall through to the full suite).

Do not use it to author missing journeys (that is create-perf-tests, unless nested after the release sufficiency ask). Do not point it at production unless policy and you explicitly allow it. Do not use it as a substitute for SmartTests.

Prompt

/testchimp run-perf-tests
/testchimp run perf
/testchimp run performance tests
/testchimp run performance tests for release 1.2.0

Synonyms: /testchimp run-perf-tests, /testchimp run perf, /testchimp run performance tests, /testchimp run performance tests for release <label> (release detail CTA).

Scope

Optional. When omitted:

• Feature / PR branch — related journeys for the change set (select-related.sh + list-related-perf-tests: scenarios, operations, paths, parent composites).
• Default branch — changes since the last run-perf-tests run.

Name files or a folder to override related selection. A release label (for release 1.2.0) switches the git range to prior SHA → cut SHA—not the working-tree branch tip. See Workflows intro — Scope.

Prerequisites

• Org capability PERFORMANCE_TESTING (or trial).
• connect-to-test-env — resolved BASE_URL / backend; isolated env for load/volume.
• TESTCHIMP_API_KEY (and backend/ingress URLs when configured) on the k6 process, not only MCP.
• k6/ scaffold (nested init-perf if missing) and at least one runnable journey—or be ready to approve nested authoring on a release.
• Policy capacity numbers for any profile other than smoke. Outbound deps stubbed with realistic latency for load/volume.

Policy

Default: plans/knowledge/policies/run-perf-tests.policy.md.

Owns permitted environments, capacity model (prod VU target vs local downsample), dependency mock/latency inventory, and LLM mode. Production is rejected unless this file and the user authorize it. Smoke is the safe default (max_vus: 1).

How to use — PR / branch

1. Finish (or skip) authoring. Related selection only finds journeys that already exist.

2. /testchimp run-perf-tests (optionally for checkout). Approve env, profile (smoke vs approved load/volume), and dataset.

3. Agent executes only through run.sh:

   k6/scripts/prepare.sh
   SEED_COMMAND=<project seed> k6/scripts/run.sh --impacted
   # or named files / full suite:
   SEED_COMMAND=<project seed> k6/scripts/run.sh journeys/foo.js
   SEED_COMMAND=<project seed> k6/scripts/run.sh

   Never bare k6 run—no ingest, no Executions charts. Paths are relative to k6/ (journeys/foo.js). Volume journeys (testTypes + volumeKind) run as a staircase so the detail page can chart volume size instead of a flat 1 VU. /testchimp run QA authors the --impacted json on the PR.

4. Open Executions → Performance Tests. Overlay a comparable prior run when dimensions match.

How to use — release

1. From the release page, paste:

   /testchimp run performance tests for release <label>

2. Agent fetches get-release (cut SHA, prior SHA), builds related selection from that diff, exports TESTCHIMP_RELEASE and the cut SHA on every wrapper run.

3. Sufficiency gate (blocking ask): if nothing covers the range (empty related set, changed operations with no tags, high-priority scenarios without PERF_TEST coverage), it tells you what changed vs what would run and asks whether to author.

   • Yes — nested create-perf-tests on the same git range, then execute new + already-related tests.
   • No — run existing related only (or stop if none); gap recorded on the plan.

4. Review ingest on the release Performance Tests panel and Executions.

Cloud automation: Run performance tests when a release is cut.

What it does

Plan → approve → Execute → Validate → Report:

1. Soft-gates capability; exports runner env (TESTCHIMP_API_KEY, TESTCHIMP_RELEASE when targeting a release).
2. Resolves target via connect-to-test-env.
3. Builds related selection; for a release, uses prior SHA → cut SHA.
4. Optional nested create (release only, after you confirm).
5. Seeds if the dataset requires it; runs k6/scripts/run.sh (load then volume); expects TestChimp perf ingest ok and usually timeseries attach ok.
6. compare-perf-to-baseline when environment, profile, dataset, LLM mode, and mock/latency profile match. CLI exits nonzero when comparison.regressed is true. Missing/mismatched baseline is incomparable, not a pass. Thresholds are not weakened implicitly.

See also

• When to use which
• Viewing results
• Create performance tests
• Skill playbook: run-perf-tests.md