fitzzftw.develtool.testinfra.TestHomeEnvironment

fromfitzzftw.develtool.testinfra import TestHomeEnvironment

class TestHomeEnvironment

Bases: object

Manages a physical test directory on the real filesystem.

This class provides a sandbox by redirecting the user’s HOME and related environment variables to a specific test directory. This isolates the developer’s actual system from side effects during test execution.

Public Data Attributes:

docinclude
base_dir	The root of the test environment (ro).
HOME	Alias for base_dir to provide intuitive access to the simulated HOME (ro).
input_dir	Read-only directory containing Git-tracked test files (ro).
output_dir	Writable directory for test execution (ro).
input_readonly	Control the write permissions of the testinput directory (rw).
do_not_clean	Toggle the automatic cleaning of the test directory (rw).

Public Methods:

__init__(base_dir)	Initialize the environment paths.
__repr__()	Return repr(self).
setup([clean_output])	Prepare the environment, redirect HOME, and switch to output_dir.
copy2config(app_name, source_name[, target_name])	Copy a file from testinput to the OS-specific user config directory.
copy2data(app_name, source_name[, target_name])	Copy a file from testinput to the OS-specific user data directory.
copy2cache(app_name, source_name[, target_name])	Copy a file from testinput to the OS-specific user cache directory.
copy2cwd(source_name[, target_name])	Copy a file from testinput directly to the current working directory.
cwd2doc_inc(filename[, target_name])	Copies a file from the current working directory (CWD) to the documentation includes directory (testdocinc).
teardown()	Restore the original environment variables and working directory.
clean_home()	Remove all files and directories from the simulated HOME except testinput.

Private Methods:

_copy_to_user_dir(app_name, source_name, ...)

Internal helper for deploying files from testinput to user directories.

---

property HOME: Path

Alias for base_dir to provide intuitive access to the simulated HOME (ro).

__init__(base_dir)

Initialize the environment paths.

Parameters:

base_dir (Path) – Path to the directory acting as the test anchor.

property base_dir: Path

The root of the test environment (ro).

clean_home()

Remove all files and directories from the simulated HOME except testinput.

This method cleans the sandbox while preserving the static input files required for further tests. The cleaning process can be suppressed by setting the property do_not_clean to True. If the property is active, calling this method will have no effect on the file system.

copy2cache(app_name, source_name, target_name=None)

Copy a file from testinput to the OS-specific user cache directory.

Parameters:

• app_name (str) – Name of the application.

• source_name (str) – Filename inside input_dir.

• target_name (str) – Optional new name at the destination.

Raises:

FileNotFoundError – If the source file is missing.

Returns:

The path to the newly created cache file.

Return type:

Path

copy2config(app_name, source_name, target_name=None)

Copy a file from testinput to the OS-specific user config directory.

Parameters:

• app_name (str) – Name of the application.

• source_name (str) – Filename inside input_dir.

• target_name (str) – Optional new name at the destination.

Raises:

FileNotFoundError – If the source file is missing.

Returns:

The path to the newly created configuration file.

Return type:

Path

copy2cwd(source_name, target_name=None)

Copy a file from testinput directly to the current working directory.

As setup() changes the CWD to output_dir, this method places files directly into the active test sandbox.

Parameters:

• source_name (str) – Filename inside input_dir.

• target_name (str) – Optional new name in the current directory.

Raises:

FileNotFoundError – If the source file is missing.

Returns:

The path to the newly created file in the CWD.

Return type:

Path

copy2data(app_name, source_name, target_name=None)

Copy a file from testinput to the OS-specific user data directory.

Parameters:

• app_name (str) – Name of the application.

• source_name (str) – Filename inside input_dir.

• target_name (str) – Optional new name at the destination.

Raises:

FileNotFoundError – If the source file is missing.

Returns:

The path to the newly created data file.

Return type:

Path

cwd2doc_inc(filename, target_name=None)

Copies a file from the current working directory (CWD) to the documentation includes directory (testdocinc).

This allows persisting files generated during tests (like patches or configurations) for use in Sphinx documentation, even if the CWD is cleaned up later.

Parameters:

• filename (str | Path) – Name or path of the source file in the CWD.

• target_name (str | None) – Optional new name for the destination file.

Returns:

The path to the copied file in the ‘testdocinc’ directory.

Raises:

FileNotFoundError – If the source file does not exist in the CWD.

Return type:

Path

property do_not_clean: bool

Toggle the automatic cleaning of the test directory (rw).

Parameters:

value – The boolean state to enable or disable cleaning.

Returns:

The current state of the cleaning lock.

property input_dir: Path

Read-only directory containing Git-tracked test files (ro).

property input_readonly: bool

Control the write permissions of the testinput directory (rw).

Parameters:

value – Set to True to make the directory read-only, False for writable (Setter).

property output_dir: Path

Writable directory for test execution (ro).

setup(clean_output=True)

Prepare the environment, redirect HOME, and switch to output_dir.

Parameters:

clean_output (bool) – If True, existing output files are deleted.

Raises:

OSError – If directories cannot be created or deleted.

teardown()

Restore the original environment variables and working directory.