{"id":5436,"library":"pytest-shutil","title":"pytest-shutil","description":"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.","status":"active","version":"1.8.1","language":"en","source_language":"en","source_url":"https://github.com/man-group/pytest-plugins","tags":["pytest","testing","fixtures","shell utilities","environment management","filesystem","temp directory"],"install":[{"cmd":"pip install pytest-shutil","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core testing framework that pytest-shutil extends.","package":"pytest"}],"imports":[{"note":"The 'workspace' fixture is automatically discovered by pytest once pytest-shutil is installed.","symbol":"workspace","correct":"def test_something(workspace):"},{"symbol":"run","correct":"from pytest_shutil.run import run"},{"symbol":"set_env","correct":"from pytest_shutil.env import set_env"}],"quickstart":{"code":"import pytest\nfrom pathlib import Path\n\n# To make the workspace fixture available, pytest-shutil must be installed.\n# No explicit import is usually needed for fixtures when installed as a plugin.\n\ndef test_create_file_and_run_script(workspace):\n    \"\"\"Demonstrates using the workspace fixture to create a file and run a shell command.\"\"\"\n    # 'workspace' is a pathlib.Path object pointing to a temporary directory\n    assert isinstance(workspace.workspace, Path)\n\n    # Create a simple shell script in the workspace\n    script_content = \"\"\"#!/bin/bash\n    echo \"Hello from $1!\"\n    \"\"\"\n    script_path = workspace.workspace / 'hello.sh'\n    script_path.write_text(script_content)\n    script_path.chmod(0o755) # Make it executable\n\n    # Run the script relative to the workspace\n    result = workspace.run('./hello.sh World', check=True, capture=True)\n\n    assert result.returncode == 0\n    assert \"Hello from World!\" in result.stdout\n    print(result.stdout)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python environment to 3.6 or newer. Review code for Python 2/early 3.x specific constructs.","message":"Version 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.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"Migrate `path.py` usage to `pathlib.Path` objects. Replace `mock` imports and usage with `unittest.mock`.","message":"As 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.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"If shell features are needed, modify `workspace.run()` calls to `workspace.run('your_command', shell=True, ...)`.","message":"Since 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()`.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}