hbutils.testing.simulate

Overview:

Simulation module for special behaviors in Python.

This module provides utilities for simulating and testing special Python behaviors, such as module imports, attribute access, and other runtime characteristics. It is primarily used for testing purposes to create controlled environments that mimic specific Python runtime scenarios.

The module re-exports all utilities from the entry submodule, which focuses on simulating CLI entry point execution for testing purposes.

simulate_entry

hbutils.testing.simulate.simulate_entry(entry: Callable, argv: List[str] | None = None, envs: Mapping[str, str] | None = None) → EntryRunResult

Overview:

CLI entry’s simulation. Executes a CLI entry function in a controlled environment, capturing its output, exit code, and any exceptions for testing purposes.

Parameters:

• entry (Callable) – Entry function, should be a simple function without any arguments.

• argv (Optional[List[str]]) – Command line arguments. Default is None, which means do not mock sys.argv.

• envs (Optional[Mapping[str, str]]) – Environment arguments. Default is None, which means do not mock os.environ.

Returns:

A result object containing exit code, stdout, stderr, and error information.

Return type:

EntryRunResult

Examples::

We create a simple CLI code with click package, named test_cli1.py

import sys
import click

@click.command('cli1', help='CLI-1 example')
@click.option('-c', type=int, help='optional C value', default=None)
@click.argument('a', type=int)
@click.argument('b', type=int)
def cli1(a, b, c):
    if c is None:
        print(f'{a} + {b} = {a + b}')
    else:
        print(f'{a} + {b} + {c} = {a + b + c}', file=sys.stderr)

if __name__ == '__main__':
    cli1()

When we can try to simulate it.

>>> from hbutils.testing import simulate_entry
>>> from test_cli1 import cli1
>>> r1 = simulate_entry(cli1, ['cli1', '2', '3'])
>>> print(r1.exitcode)
0
>>> print(r1.stdout)
2 + 3 = 5

>>> r2 = simulate_entry(cli1, ['cli1', '2', '3', '-c', '24'])  # option
>>> print(r2.exitcode)
0
>>> print(r2.stderr)
2 + 3 + 24 = 29

>>> r3 = simulate_entry(cli1, ['cli', '--help'])  # help
>>> print(r3.stdout)
Usage: cli [OPTIONS] A B
  CLI-1 example
Options:
  -c INTEGER  optional C value
  --help      Show this message and exit.

>>> r4 = simulate_entry(cli1, ['cli', 'dklsfj'])  # misusage
>>> print(r4.exitcode)
2
>>> print(r4.stderr)
Usage: cli [OPTIONS] A B
Try 'cli --help' for help.
Error: Invalid value for 'A': 'dklsfj' is not a valid integer.

Note

Please note that if there is uncaught exception raised inside the entry function, it will be caught and put into error property instead of being printed to stderr. For example

>>> from hbutils.testing import simulate_entry
>>> def my_cli():
...     raise ValueError(233)
>>>
>>> r = simulate_entry(my_cli)
>>> print(r.exitcode)  # will be 0x1
1
>>> print(r.stdout)  # nothing
>>> print(r.stderr)  # nothing as well
>>> print(repr(r.error))  # HERE!!!
ValueError(233)

EntryRunResult

class hbutils.testing.simulate.EntryRunResult(exitcode: int, stdout: str | None, stderr: str | None, error: BaseException | None)

Overview:

Run result of one entry. This class encapsulates the results of executing a CLI entry function, including exit code, stdout/stderr output, and any uncaught exceptions.

__init__(exitcode: int, stdout: str | None, stderr: str | None, error: BaseException | None)

Constructor of EntryRunResult.

Parameters:

• exitcode (int) – Exit code returned by the entry function.

• stdout (Optional[str]) – Output captured from standard output stream.

• stderr (Optional[str]) – Output captured from standard error stream.

• error (Optional[BaseException]) – Uncaught exception raised inside the entry function.

property error: BaseException | None

Uncaught exception raised inside the entry function.

Returns:

The exception object, or None if no exception was raised.

Return type:

Optional[BaseException]

property exitcode: int

Exit code returned by the entry function.

Returns:

The exit code value.

Return type:

int

property stderr: str | None

Output captured from standard error stream.

Returns:

The stderr content, or None if no output was captured.

Return type:

Optional[str]

property stdout: str | None

Output captured from standard output stream.

Returns:

The stdout content, or None if no output was captured.

Return type:

Optional[str]