pytest-shutil

library1.8.1pypypi✓ verified 24d ago

pytest-shutil is a Python library offering a collection of Unix shell and environment management tools specifically designed for automated tests with `pytest`. It provides fixtures and utilities to streamline tasks such as managing temporary directories (workspaces), executing shell commands, and manipulating environment variables within test contexts. Currently at version 1.8.1, it is actively maintained with recent updates addressing Python compatibility and modern best practices.

testing

pip install pytest-shutil

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-SHUTIL

pytest-shutil

testingpythonv1.8.1

Install

3.0s avg

Import

—

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 31.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.0s · import 0.000s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

workspace

✓ def test_something(workspace):

The 'workspace' fixture is automatically discovered by pytest once pytest-shutil is installed.

run

✓ from pytest_shutil.run import run

set_env

✓ from pytest_shutil.env import set_env

This quickstart demonstrates the core `workspace` fixture, which provides a function-scoped temporary directory as a `pathlib.Path` object. It shows how to create an executable script within this workspace and then run it using `workspace.run()` to capture output and check the return code.

import pytest from pathlib import Path # To make the workspace fixture available, pytest-shutil must be installed. # No explicit import is usually needed for fixtures when installed as a plugin. def test_create_file_and_run_script(workspace): """Demonstrates using the workspace fixture to create a file and run a shell command.""" # 'workspace' is a pathlib.Path object pointing to a temporary directory assert isinstance(workspace.workspace, Path) # Create a simple shell script in the workspace script_content = """#!/bin/bash echo "Hello from $1!" """ script_path = workspace.workspace / 'hello.sh' script_path.write_text(script_content) script_path.chmod(0o755) # Make it executable # Run the script relative to the workspace result = workspace.run('./hello.sh World', check=True, capture=True) assert result.returncode == 0 assert "Hello from World!" in result.stdout print(result.stdout)

Debug

Known issues

breakingVersion 1.8.0 dropped support for Python 2 and Python versions less than 3.6. Code relying on older Python syntax or features will break.

fix

Upgrade Python environment to 3.6 or newer. Review code for Python 2/early 3.x specific constructs.

affects: >=1.8.0

breakingAs of version 1.8.0, `pytest-shutil` replaced `path.py` with `pathlib` for path objects and switched from the `mock` package to Python's standard library `unittest.mock`. Code directly interacting with `path.py` objects or the external `mock` library within `pytest-shutil`'s context will need updates.

fix

Migrate `path.py` usage to `pathlib.Path` objects. Replace `mock` imports and usage with `unittest.mock`.

affects: >=1.8.0

gotchaSince version 1.1.0, `workspace.run()`'s default behavior changed to *not* use a subshell for security reasons. If your command requires shell features (e.g., pipes, redirects, environment variable expansion like `$VAR`), you must explicitly pass `shell=True` to `workspace.run()`.

fix

If shell features are needed, modify `workspace.run()` calls to `workspace.run('your_command', shell=True, ...)`.

affects: >=1.1.0

Errors

Common errors & fixes

pytest.FixtureLookupError: fixture 'workspace' not found

The 'workspace' fixture is not recognized by pytest, usually because pytest-shutil is not installed or not accessible in the test environment.

fix

Ensure pytest-shutil is installed in your testing environment. If it is, verify that pytest is correctly discovering your test files.

TypeError: 'PosixPath' object is not callable

The 'workspace' fixture provides a path-like object (e.g., pathlib.PosixPath), which should be used directly to construct paths, not called like a function.

fix

Use the 'workspace' object directly as a path without attempting to call it. (e.g., `workspace / 'my_file.txt'` instead of `workspace() / 'my_file.txt'`).

ImportError: cannot import name 'workspace' from 'pytest_shutil'

The 'workspace' (or other) utilities from pytest-shutil are designed as pytest fixtures, which are injected into test functions, not imported directly from the module.

fix

Remove the direct import statement. Instead, include 'workspace' as an argument in your test function signature to access the fixture.

TypeError: argument of type 'CommandResult' is not iterable

The 'sh' fixture returns a `CommandResult` object, not a simple string. You cannot directly iterate over or search within the `CommandResult` object.

fix

Access the `stdout` or `stderr` attributes of the `CommandResult` object to work with the command's output as strings.

Upgrade

Version history

1.8.1latest on PyPI · released Nov 29, 2024

Audit

Dependencies

pytestrequiredCore testing framework that pytest-shutil extends.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/man-group/pytest-plugins ↗

packagehttps://pypi.org/project/pytest-shutil/ ↗