CLI Module¶

The CLI module provides steps for shell command execution with subprocess, capturing exit code, stdout and stderr — 10 steps in total, all with es and pt translations.

Installation¶

The CLI module has no third-party dependencies. It uses only the Python standard library (subprocess, re). No extra is needed — the CLI module is always available when steplib is installed.

Context¶

The CLIContext lives at context.steplib.cli. It holds:

exit_code — the exit code of the last executed command (int | None).
stdout — the stdout output of the last command (str).
stderr — the stderr output of the last command (str).
variables — a dict[str, Any] for stored command outputs.

def before_all(context):
    context.steplib = autoload(context)

def before_scenario(context, scenario):
    context.steplib.reset()  # clears exit_code, stdout, stderr, variables

def after_scenario(context, scenario):
    context.steplib.cleanup()  # same as reset

Steps¶

Command execution¶

Pattern	Description
`I run the command {command}`	Run a shell command and store exit code, stdout and stderr.
`I run the command {command} with timeout {timeout:d} seconds`	Run a shell command with a timeout (raises on expiry).

Exit code assertions¶

Pattern	Description
`the command exit code is {code:d}`	Assert that the last command’s exit code equals a value.

Stdout assertions¶

Pattern	Description
`the command output contains {text}`	Assert that stdout contains the given text.
`the command output does not contain {text}`	Assert that stdout does NOT contain the given text.
`the command output equals {text}`	Assert that stdout equals the given text.
`the command output matches the pattern {pattern}`	Assert that stdout matches a regex pattern.

Stderr assertions¶

Pattern	Description
`the command stderr contains {text}`	Assert that stderr contains the given text.

Store operations¶

Pattern	Description
`I store the command output as {variable}`	Store the last command’s stdout into a variable.
`I store the command error output as {variable}`	Store the last command’s stderr into a variable.

Example¶

Feature: CLI command testing

  Scenario: Run and assert output
    When I run the command "echo hello"
    Then the command exit code is 0
    And the command output contains "hello"
    And the command output does not contain "error"
    And the command output matches the pattern "hell."
    When I store the command output as "result"
    Then the variable "result" contains "hello"

  Scenario: Error output
    When I run the command "echo error 1>&2"
    Then the command exit code is 0
    And the command stderr contains "error"
    When I store the command error output as "errors"
    Then the variable "errors" contains "error"

  Scenario: Timeout
    When I run the command "sleep 10" with timeout 1 seconds
    # raises subprocess.TimeoutExpired

API reference¶

See Modules API Reference for the full autodoc reference of the CLI module.