hbutils.testing.capture

Overview:

Utilities for capturing different kinds of results, which can be useful in testing.

This module provides tools for capturing program exit behavior and output streams during testing. It includes functionality to intercept system exits and capture stdout/stderr output, making it easier to test code that produces side effects.

The module exports all functionality from its submodules:

• exit: Utilities for capturing and testing system exit behavior

• output: Utilities for capturing stdout/stderr output streams

capture_output

hbutils.testing.capture.capture_output(mem: bool = False) → ContextManager[OutputCaptureResult]

Overview:

Capture all the output to sys.stdout and sys.stderr in this with block.

Parameters:

mem (bool) – Use memory to put the result or not. Default is False which means the output will be redirected to temporary files.

Returns:

A context manager yielding an OutputCaptureResult object containing captured output.

Return type:

ContextManager[OutputCaptureResult]

Examples::

>>> from hbutils.testing import capture_output
>>> import sys
>>>
>>> with capture_output() as r:
...     print('this is stdout')
...     print('this is stderr', file=sys.stderr)
...
>>> r.stdout
'this is stdout\n'
>>> r.stderr
'this is stderr\n'

Note

When mem is set to True, io.StringIO is used, which does not have fileno method. This may cause some problems in some cases (such as subprocess.run()). Use mem=False (default) for compatibility with subprocess operations.

OutputCaptureResult

class hbutils.testing.capture.OutputCaptureResult

Overview:

Result model of output capturing. This class stores captured stdout and stderr content and provides thread-safe access to the results.

__init__()

Constructor of OutputCaptureResult.

Initializes the result object with None values for stdout and stderr, and creates a lock that is initially acquired to prevent premature access.

put_result(stdout: str | None, stderr: str | None)

Put result inside this model.

Parameters:

• stdout (Optional[str]) – Stdout result content.

• stderr (Optional[str]) – Stderr result content.

property stderr: str | None

Stderr of the output result.

Returns:

The captured stderr content.

Return type:

Optional[str]

Note

Do not use this property when capture_output()’s with block is not exited, or this property will be blocked due to the deadlock inside.

property stdout: str | None

Stdout of the output result.

Returns:

The captured stdout content.

Return type:

Optional[str]

Note

Do not use this property when capture_output()’s with block is not exited, or this property will be blocked due to the deadlock inside.

disable_output

hbutils.testing.capture.disable_output(encoding: str = 'utf-8') → ContextManager[None]

Overview:

Disable all the output to sys.stdout and sys.stderr in this with block. All output will be redirected to the system’s null device (e.g., /dev/null on Unix).

Parameters:

encoding (str) – Encoding of null file, default is utf-8.

Returns:

A context manager that suppresses all stdout and stderr output.

Return type:

ContextManager[None]

Examples::

>>> import sys
>>> from hbutils.testing import disable_output
>>>
>>> with disable_output():  # no output will be shown
...     print('this is stdout')
...     print('this is stderr', file=sys.stderr)

capture_exit

hbutils.testing.capture.capture_exit(default: int = 0) → ContextManager[ExitCaptureResult]

Overview:

Capture for exitcode, quit() and sys.exit() can be captured. This context manager intercepts system exit calls and stores the exit code in an ExitCaptureResult object instead of terminating the process.

Parameters:

default (int) – Default exitcode when no exit is called, default is 0.

Returns:

A context manager that yields an ExitCaptureResult object.

Return type:

ContextManager[ExitCaptureResult]

Examples::

>>> from hbutils.testing import capture_exit
>>> with capture_exit() as ex:
...     pass
>>> ex.exitcode
0
>>>
>>> with capture_exit() as ex:
...     quit()
>>> ex.exitcode
0
>>>
>>> with capture_exit() as ex:
...     quit(0xf)
>>> ex.exitcode
15
>>>
>>> import sys
>>> with capture_exit() as ex:
...     sys.exit(0xf)
>>> ex.exitcode
15

ExitCaptureResult

class hbutils.testing.capture.ExitCaptureResult(exitcode)

Overview:

Model of exit capture result. This class stores the captured exit code from a context where system exits are intercepted.

__init__(exitcode)

Constructor of ExitCaptureResult.

Parameters:

exitcode (int) – Initial exitcode value.

property exitcode: int

Get the captured exitcode value.

Returns:

The exit code that was captured.

Return type:

int

Note

Do not use this property when capture_exit() is not over, otherwise this result is not guaranteed to be correct.

put_result(exitcode: int)

Put result inside this model.

Parameters:

exitcode (int) – New exitcode value to store.