Skip to content

carapace-sh/carapace-bin / skills/typer

Use when building CLI applications with fastapi/typer — creating commands, defining CLI arguments and options, type-hint-driven parameter parsing, callbacks, context, help customization, shell completion, testing, packaging, or Typer internals. Triggers on: "typer", "typer.run", "typer.Typer", "typer app", "typer command", "typer argument", "typer option", "typer callback", "typer context", "Annotated", "typer.Argument", "typer.Option", "typer.Context", "CliRunner", "add_typer", "rich_markup_mode", "typer completion", "typer autocompletion", "typer echo", "typer test", "typer package", "typer click", "get_command".

FileKindSize
SKILL.mdskill md5.1 KB
references/commands.mdmarkdown6.4 KB
references/completion.mdmarkdown4.3 KB
references/context.mdmarkdown4.9 KB
references/help-output.mdmarkdown4.5 KB
references/internals.mdmarkdown7.4 KB
references/package.mdmarkdown2.8 KB
references/parameter-types.mdmarkdown5.6 KB
references/parameters.mdmarkdown6.9 KB
references/testing.mdmarkdown3.2 KB

references/testing.md

View on GitHub
# Testing Typer Apps

Testing CLI applications with pytest and `typer.testing.CliRunner`.

> **Source of truth**: <https://typer.tiangolo.com/tutorial/testing/>. For `Result` internals, see [internals.md](internals.md).

## Basic Pattern

```python
from typer.testing import CliRunner
from myapp.main import app  # your typer.Typer() app

runner = CliRunner()

def test_app():
    result = runner.invoke(app, ["hello", "Camila"])
    assert result.exit_code == 0
    assert "Hello Camila" in result.output
```

`runner.invoke(app, args)` builds the Click command via `get_command(app)` and executes it with the given args, capturing stdout/stderr.

## Checking Results

`Result` exposes:

| Attribute | Description |
|-----------|-------------|
| `exit_code` | Process exit code (0 on success, 2 on usage errors) |
| `output` | Combined stdout+stderr as str (matches what users see) |
| `stdout`, `stderr` | Separately captured streams |
| `exception` | Unhandled exception, if `catch_exceptions=True` (default) |
| `exc_info` | Exception traceback info |

With `catch_exceptions=True` (default) an unhandled exception is captured into `result.exception` instead of failing the test; assert on `result.exit_code != 0` and `result.exception`.

## Testing Errors and Edge Cases

```python
def test_missing_arg():
    result = runner.invoke(app, ["hello"])
    assert result.exit_code != 0
    assert "Missing argument" in result.output
```

## Testing Input (Prompts)

```python
def test_prompt():
    result = runner.invoke(app, ["hello"], input="Camila\n")
    assert "Name:" in result.output
```

`input=` simulates stdin; end each simulated line with `\n`.

## Testing a Bare Function

You can invoke a plain function (created with `typer.run`-style signatures) without an explicit app — `CliRunner.invoke` accepts functions that Typer can convert:

```python
from typer.testing import CliRunner
from myapp.main import main  # plain function

runner = CliRunner()

def test_function():
    result = runner.invoke(main, ["Camila"])
    assert result.exit_code == 0
```

Typer wraps the function in an ephemeral app under the hood.

## Isolated Filesystem and Environment

`CliRunner` (Click heritage) supports:

- `runner.invoke(app, args, env={"MY_VAR": "x"})` — temporarily set env vars.
- `with runner.isolated_filesystem():` — run in a temp directory that is cleaned up.

## Gotchas

- `@app.command()` registers into the app's global state; importing the module multiple times in tests can double-register commands. Import once (pytest caches modules).
- Rich-formatted output may include ANSI codes and wrapping; prefer substring assertions on stable words, or set `env={"NO_COLOR": "1"}` / `TERM=dumb` to reduce formatting.
- `result.output` merges stdout and stderr; use `result.stdout`/`result.stderr` when the destination matters (requires the app to write via `typer.echo(err=True)` or a Rich stderr console).
- Because `invoke` catches exceptions by default, a test asserting success should also check `result.exception is None` when unsure.

## References

- <https://typer.tiangolo.com/tutorial/testing/>
- Click's CliRunner docs (vendored implementation)

## Related

- Building the Click tree being invoked: [internals.md](internals.md)
- Output helpers: [help-output.md](help-output.md)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall