# axx run

> Start the services, run feature files, and report

Source: https://axx.nimbusxr.us/next/references/cli/axx-run/

Run Gherkin scenarios against your services.

Axx starts the applications declared in axx.yaml (only those needed by the
selected scenarios when active.enabled is set), waits until they are ready,
runs scenarios in parallel, stops the services and runs their cleanups.

Select scenarios with paths (features/x.feature:14 selects the scenario on
line 14, or the scenario containing that step line), --tags and --name.
--shard 1/3 runs a third of what they select, for CI's runners to share a run:
every third scenario, in their files' and lines' order, from the first; 2/3
and 3/3 run the rest.

Exit codes: 0 passed, 1 failures, 2 usage/config, 3 undefined/ambiguous steps,
4 a service failed to start, 130 interrupted.

```text
Usage:
  axx run [paths[:line]...] [flags]

Examples:
  axx run
  axx run features/register-parcels.feature:17
  axx run --tags "@smoke and not @wip" --format junit:build/axx/junit.xml
  axx run --shard 2/3         # one of three runners: a third of the scenarios
  axx run --attach api        # you run the api from your IDE; axx waits for it
  axx run --debug=api         # start api with its debug command
  axx run --debug-steps features/register-parcels.feature:17   # stop at breakpoints in step code
  axx run features/shop-portal.feature --pause-at features/shop-portal.feature:24   # pause before that step, where packs can show it

Flags:
      --attach strings                services you run yourself; axx waits for their readiness instead of starting them
      --debug string[="*"]            start services with their debug command (all, or a comma-separated list)
      --debug-steps string[="2345"]   run under Delve so a Go debugger can stop at breakpoints in step code (port, default 2345)
  -D, --define stringArray            set a property for ${sys:name}, e.g. -D local.host=docker
      --dry-run                       match steps without executing them or starting services
      --fail-fast                     stop scheduling scenarios after the first failure
  -f, --format stringArray            reporter NAME or NAME:FILE (repeatable): pretty, progress, compact, junit, messages, cucumber-json, html, agent, teamcity
  -h, --help                          help for run
  -n, --name stringArray              only scenarios whose name matches this regular expression (repeatable)
      --no-start                      do not start, stop or clean up any service
      --order string                  scenario order: "defined" or "random[:seed]"
      --pause-at stringArray          pause before the step at this file:line, with no timeouts, for the packs that can show a person what the scenario does (repeatable)
      --profile string                apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --rerun-file string             write failed scenario locations (file:line) to this file
      --set stringArray               set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value
      --shard string                  run shard i of n ("i/n", from 1) of the selected scenarios: every nth, in their files' and lines' order
      --slowdown string               pause after each action of a watched run, e.g. "500ms" (run.slowdown)
  -t, --tags string                   tag expression, e.g. "@smoke and not @wip"
      --watch                         show what the scenarios do as they do it: browsers and devices in their windows, one scenario at a time unless --workers says otherwise (run.watch)
  -w, --workers int                   parallel scenarios (default: run.workers, or number of CPUs)

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```