Commands

Run commands, such as a command-line tool you ship or an operator’s admin command, and check how they end and what they print.

Register a command with the {word} command with the following properties:: the program and its first arguments, split like an app’s command in axx.yaml (double quotes group words; there is no shell), the folder it runs in, its environment and its timeout. Then run it, with more arguments and, if it reads them, lines of input, and check its exit code and its output (what it prints) or its error output (what it prints to stderr).

• A command runs in a folder of its own for each scenario, unless its dir says otherwise, so parallel scenarios never write over each other’s files. The folder is removed when the scenario passes and kept when it fails.
• A program named by a relative path (bin/parcels) is found from the directory of axx.yaml; a bare name (psql) on the PATH.
• The checks look at the command’s last run in the scenario. A command that exits with a failing code does not fail the step that runs it: check its exit code. Only a command that cannot start, or runs past its timeout, fails the run step, and it shows what the command printed.
• Secrets stay secret: ${env:..} values in the properties, the arguments and the input are masked in logs, attachments and failures.
• Stopping: a command that runs past its timeout is stopped with everything it started. A command that runs a process elsewhere, such as docker compose exec, stops, but the process it started may run on.

Add it to a project with axx pack add cli.

Steps

cli.command

Given the {word} command with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register a command under a name: the program and its first arguments, where it runs, its environment and its timeout.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
command	the program and its first arguments, split like a service’s command in axx.yaml: double quotes group words, and there is no shell. A relative path to the program is from the directory of axx.yaml	required
dir	the folder it runs in, relative to the directory of axx.yaml	a folder of the scenario's own
env.<NAME>	an environment variable, set over Axx’s own environment
timeout	how long a run may take before the command is stopped, like 30s	1m

Values are expanded (${env:..}, ${sys:..}); what ${env:..} references expand to is masked everywhere.

Example:

Given the admin command with the following properties:
  | command | docker compose exec -T app parcels admin |
  | dir     | ../infra                                 |

Since 0.1.5.

cli.run

When the {word} command is run[[ with {string}]]

Run the command, with more arguments after its own, split the same way. The step waits for the command to end; it fails only when the command cannot start or runs past its timeout.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} command is run
• the {word} command is run with {string}

Example:

When the admin command is run with 'label PX-ADM-6101'

Since 0.1.5.

cli.run.input

When the {word} command is run with[[ {string} and]] the input:
  """
  ...
  """

Run the command with the doc string as its input (stdin), and more arguments if the step names them.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} command is run with the input:
• the {word} command is run with {string} and the input:

Example:

When the admin command is run with 'cancel -' and the input:
  """
  PX-ADM-6103
  PX-ADM-6104
  """

Since 0.1.5.

cli.exit

Then the {word} command's exit code is {int}

Check the exit code of the command’s last run.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{int}	a whole number	200, 3

Example:

Then the admin command's exit code is 0

Since 0.1.5.

cli.output.contains

Then the {word} command's[[ error]] output contains {string}

Check that the command’s output (or its error output) contains the text. Runs of spaces and line breaks count as one space, in both.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} command's output contains {string}
• the {word} command's error output contains {string}

Example:

Then the admin command's error output contains 'PX-ADM-6102 is DISPATCHED'

Since 0.1.5.

cli.output.line

Then the {word} command's[[ error]] output has a line matching {string}

Check that a line of the command’s output (or its error output) matches the regular expression (Java syntax), anywhere in the line; ^ and $ are the line’s start and end.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} command's output has a line matching {string}
• the {word} command's error output has a line matching {string}

Example:

Then the admin command's output has a line matching 'cancelled PX-ADM-610[34]'

Since 0.1.5.

cli.output.is

Then the {word} command's[[ error]] output is:
  """
  ...
  """

Check the command’s output (or its error output) is exactly the doc string. Windows line breaks count as plain ones, and so does one line break at the end.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Variants, the parts in [[...]] said or left out:

• the {word} command's output is:
• the {word} command's error output is:

Example:

Then the admin command's output is:
  """
  cancelled PX-ADM-6103
  cancelled PX-ADM-6104
  """

Since 0.1.5.

cli.output.empty

Then the {word} command's[[ error]] output is empty

Check that the command printed nothing at all to its output (or its error output).

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Variants, the parts in [[...]] said or left out:

• the {word} command's output is empty
• the {word} command's error output is empty

Example:

Then the admin command's error output is empty

Since 0.1.5.

cli.output.properties

Then the {word} command's output has the following properties:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check the JSON the command printed: each row is a path into it (a field name, a dotted path or a JSONPath) and the value it has.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Values compare as text: null is null and undefined is absent.

Example:

Then the admin command's output has the following properties:
  | shop                   | kestrel-books |
  | parcels[0].reference   | PX-ADM-6105   |
  | parcels[0].serviceLevel | EXPRESS       |

Since 0.1.5.

cli.output.identical

Then the {word} command's output is identical to the {filepath} file

Check that the command’s output is, byte for byte, the file of the project.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json

Example:

Then the admin command's output is identical to the labels/PX-ADM-6101.zpl file

Since 0.1.5.