{"id":20287612,"url":"https://github.com/rhettbull/clirunner","last_synced_at":"2025-07-05T06:02:02.049Z","repository":{"id":209653341,"uuid":"724173057","full_name":"RhetTbull/clirunner","owner":"RhetTbull","description":"A python test helper for invoking and testing command line interfaces (CLIs) based on Click's CliRunner","archived":false,"fork":false,"pushed_at":"2023-12-09T17:33:12.000Z","size":639,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T06:41:38.496Z","etag":null,"topics":["cli","command-line","command-line-tool","pytest","python","test","testing","unittest","unittesting"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RhetTbull.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-11-27T14:43:34.000Z","updated_at":"2024-03-10T06:03:26.000Z","dependencies_parsed_at":"2023-12-14T23:11:47.858Z","dependency_job_id":null,"html_url":"https://github.com/RhetTbull/clirunner","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"4ca69852681aa68e77dab54277c62e36ce7f537e"},"previous_names":["rhettbull/clirunner"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhetTbull%2Fclirunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhetTbull%2Fclirunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhetTbull%2Fclirunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhetTbull%2Fclirunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RhetTbull","download_url":"https://codeload.github.com/RhetTbull/clirunner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248369511,"owners_count":21092608,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","command-line-tool","pytest","python","test","testing","unittest","unittesting"],"created_at":"2024-11-14T14:41:03.905Z","updated_at":"2025-04-11T09:45:14.231Z","avatar_url":"https://github.com/RhetTbull.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CliRunner\n\nA test helper for invoking and testing command line interfaces (CLIs). This is adapted from the [Click](https://click.palletsprojects.com/) [CliRunner](https://click.palletsprojects.com/en/8.1.x/testing/) but modified to work with non-Click scripts, such as those using [argparse](https://docs.python.org/3/library/argparse.html) for parsing command line arguments.\n\n## Installation\n\n`python3 -m pip install clirunner`\n\n## Source Code\n\nThe source code is available on [GitHub](https://github.com/RhetTbull/clirunner).\n\n## Motivation\n\nI write a lot of Python command line tools. I usually reach for Click to build the CLI but sometimes will use argparse or even just manual `sys.argv` parsing for simple scripts or where I do not want to introduce a dependency on Click. Click provides a very useful [CliRunner](https://click.palletsprojects.com/en/8.1.x/testing/) for testing CLIs, but it only works with Click applications. This project is a derivative of Click's CliRunner that works with non-Click scripts. The API is the same as Click's CliRunner, so it should be easy to switch between the two if you later refactor to use Click.\n\n## Supported Platforms\n\nTested on macOS, Ubuntu Linux, and Windows using \"*-latest\" GitHub Workflow runners with Python 3.9 - 3.12.\n\n## Documentation\n\nFull documentation is available [here](https://rhettbull.github.io/clirunner/).\n\n## Basic Testing\n\nCliRunner can invoke your CLI's main function as a command line script. The CliRunner.invoke() method runs the command line script in isolation and captures the output as both bytes and binary data.\n\nThe return value is a Result object, which has the captured output data, exit code, and optional exception attached:\n\n### hello.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/hello.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Simple CLI \"\"\"\n\nimport argparse\n\n\ndef hello():\n    \"\"\"Print Hello World\"\"\"\n    argp = argparse.ArgumentParser(description=\"Print Hello World\")\n    argp.add_argument(\"-n\", \"--name\", help=\"Name to greet\")\n    args = argp.parse_args()\n    print(f\"Hello {args.name or 'World'}!\")\n\n\nif __name__ == \"__main__\":\n    hello()\n```\n\u003c!--[[[end]]]--\u003e\n\n### test_hello.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/test_hello.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Test hello.py\"\"\"\n\nfrom hello import hello\n\nfrom clirunner import CliRunner\n\n\ndef test_hello_world():\n    runner = CliRunner()\n    result = runner.invoke(hello, [\"--name\", \"Peter\"])\n    assert result.exit_code == 0\n    assert result.output == \"Hello Peter!\\n\"\n```\n\u003c!--[[[end]]]--\u003e\n\nNote that `result.output` will contain the combined output of `stdout` and `stderr`. If you want to capture `stdout` and `stderr` separately, use `result.stdout` and `result.stderr`.\n\n## File System Isolation\n\nFor basic command line tools with file system operations, the `CliRunner.isolated_filesystem()` method is useful for setting the current working directory to a new, empty folder.\n\n### cat.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/cat.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Simple cat program for testing isolated file system\"\"\"\n\nimport argparse\n\n\ndef cat():\n    argp = argparse.ArgumentParser()\n    argp.add_argument(\"file\", type=argparse.FileType(\"r\"))\n    args = argp.parse_args()\n    print(args.file.read(), end=\"\")\n\n\nif __name__ == \"__main__\":\n    cat()\n```\n\u003c!--[[[end]]]--\u003e\n\n### test_cat.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/test_cat.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Test cat.py example.\"\"\"\n\nfrom cat import cat\n\nfrom clirunner import CliRunner\n\n\ndef test_cat():\n    runner = CliRunner()\n    with runner.isolated_filesystem():\n        with open(\"hello.txt\", \"w\") as f:\n            f.write(\"Hello World!\\n\")\n\n        result = runner.invoke(cat, [\"hello.txt\"])\n        assert result.exit_code == 0\n        assert result.output == \"Hello World!\\n\"\n```\n\u003c!--[[[end]]]--\u003e\n\nPass `temp_dir` to control where the temporary directory is created. The directory will not be removed by `CliRunner` in this case. This is useful to integrate with a framework like Pytest that manages temporary files.\n\n```python\ndef test_keep_dir(tmp_path):\n    runner = CliRunner()\n\n    with runner.isolated_filesystem(temp_dir=tmp_path) as td:\n        ...\n```\n\n## Input Streams\n\nThe test wrapper can also be used to provide input data for the input stream (stdin). This is very useful for testing prompts, for instance:\n\n### prompt.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/prompt.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Simple example for testing input streams\"\"\"\n\n\ndef prompt():\n    foo = input(\"Foo: \")\n    print(f\"foo = {foo}\")\n\n\nif __name__ == \"__main__\":\n    prompt()\n```\n\u003c!--[[[end]]]--\u003e\n\n### test_prompt.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/test_prompt.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Test prompt.py example\"\"\"\n\nfrom prompt import prompt\n\nfrom clirunner import CliRunner\n\n\ndef test_prompts():\n    runner = CliRunner()\n    result = runner.invoke(prompt, input=\"wau wau\\n\")\n    assert not result.exception\n    # note: unlike click.CliRunner, clirunner.CliRunner does not echo the input\n    assert \"foo = wau wau\\n\" in result.output\n```\n\u003c!--[[[end]]]--\u003e\n\nNote that the input will not be echoed to the output stream. This is different from the behavior of the `input()` function, which does echo the input and from click's `prompt()` function, which also echo's the input when under test.\n\n## Environment Variable Isolation\n\nThe `CliRunner.invoke()` method can also be used to set environment variables for the command line script. This is useful for testing command line tools that use environment variables for configuration.\n\n### hello_env.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/hello_env.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Say hello to the world, shouting if desired.\"\"\"\n\nimport os\n\n\ndef hello():\n    \"\"\"Say hello to the world, shouting if desired.\"\"\"\n    if os.getenv(\"SHOUT\") == \"1\":\n        print(\"HELLO WORLD!\")\n    else:\n        print(\"Hello World!\")\n\n\nif __name__ == \"__main__\":\n    hello()\n```\n\u003c!--[[[end]]]--\u003e\n\n### test_hello_env.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/test_hello_env.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Test hello2.py showing how to set environment variables for testing.\"\"\"\n\nfrom hello_env import hello\n\nfrom clirunner import CliRunner\n\n\ndef test_hello():\n    \"\"\"Test hello2.py\"\"\"\n    runner = CliRunner()\n    result = runner.invoke(hello)\n    assert result.exit_code == 0\n    assert result.output == \"Hello World!\\n\"\n\n\ndef test_hello_shouting():\n    \"\"\"Test hello2.py\"\"\"\n    runner = CliRunner()\n    result = runner.invoke(hello, env={\"SHOUT\": \"1\"})\n    assert result.exit_code == 0\n    assert result.output == \"HELLO WORLD!\\n\"\n```\n\u003c!--[[[end]]]--\u003e\n\n## Handling Exceptions\n\nNormally the `CliRunner.invoke()` method will catch exceptions in the CLI under test. If an exception is raised, it will be available via the `Result.exception` property. This can be disabled by passing `catch_exceptions=False` to the `CliRunner.invoke()` method.\n\n### raise_exception.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/raise_exception.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Simple script that raises an exception\"\"\"\n\n\ndef raise_exception():\n    \"\"\"Raises a ValueError exception\"\"\"\n    raise ValueError(\"Exception raised\")\n\n\nif __name__ == \"__main__\":\n    raise_exception()\n```\n\u003c!--[[[end]]]--\u003e\n\n### test_raise_exception.py\n\n\u003c!--[[[cog\ncog.out(\"\\n```python\\n\")\nwith open(\"tests/test_raise_exception.py\", \"r\") as f:\n    cog.out(f.read())\ncog.out(\"```\\n\")\n]]]--\u003e\n\n```python\n\"\"\"Test raise_exception.py\"\"\"\n\nimport pytest\nfrom raise_exception import raise_exception\n\nfrom clirunner import CliRunner\n\n\ndef test_exception_caught():\n    \"\"\"CliRunner normally catches exceptions\"\"\"\n    runner = CliRunner()\n    result = runner.invoke(raise_exception)\n    # exit code will not be 0 if exception is raised\n    assert result.exit_code != 0\n    assert isinstance(result.exception, ValueError)\n\n\ndef test_exception_not_caught():\n    \"\"\"CliRunner can be configured to not catch exceptions\"\"\"\n    runner = CliRunner()\n    with pytest.raises(ValueError):\n        runner.invoke(raise_exception, catch_exceptions=False)\n```\n\u003c!--[[[end]]]--\u003e\n\n## Testing Click Applications\n\nDo not use `clirunner.CliRunner` to test applications built with [Click](https://pypi.org/project/click/), [Typer](https://pypi.org/project/typer/), or another Click derivative. Instead, use Click's built-in [CliRunner](https://click.palletsprojects.com/en/8.1.x/testing) or [Typer's equivalent](https://typer.tiangolo.com/tutorial/testing/).\n\n`clirunner.CliRunner` is designed for testing non-Click scripts such as those using [argparse](https://docs.python.org/3/library/argparse.html) or manual [sys.argv](https://docs.python.org/3/library/sys.html#sys.argv) argument parsing. It has also been tested with [pydantic-argparse](https://pydantic-argparse.supimdos.com/), [clipstick](https://github.com/sander76/clipstick), and [tyro](https://github.com/brentyi/tyro).\n\n## License\n\nCliRunner is a derivative work of Click's CliRunner, and so it is licensed under the same BSD 3-clause license as Click. See the [LICENSE](https://github.com/RhetTbull/clirunner/blob/main/LICENSE) and [LICENSE.Click](https://github.com/RhetTbull/clirunner/blob/main/LICENSE.Click) files for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhettbull%2Fclirunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhettbull%2Fclirunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhettbull%2Fclirunner/lists"}