Lab: CLI coverage

Write tests that cover all three ds-tool commands — happy paths, error paths, stdin confirmation, and env var injection.

This lab writes tests for ds-tool — the multi-subcommand CLI from the Click lab. We will cover all three commands (scan, report, clean), test both the success and error paths for each, and handle the confirmation prompt in clean via CliRunner's input= parameter.

The goal is a test suite that catches regressions without being fragile. By the end you will have tests for every meaningful branch.

The tool under test

For this lab, ds-tool is defined inline so the tests are self-contained. In a real project it would live in its own module and the tests would import it.

Python — editable, runs in your browser

import click
import os
from click.testing import CliRunner

# ---- ds-tool definition ----

@click.group()
@click.pass_context
def ds(ctx):
  """Dataset management tool."""
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv")
@click.pass_obj
def scan(obj, directory, ext):
  """Scan DIRECTORY for files with the given extension."""
  if not os.path.isdir(directory):
      raise click.ClickException(f"Not a directory: {directory}")
  found = []
  for entry in os.scandir(directory):
      if entry.is_file() and entry.name.endswith(ext):
          found.append({"name": entry.name, "path": entry.path, "size": entry.stat().st_size})
  obj["results"] = found
  click.echo(f"Found {len(found)} {ext} file(s) in {directory}.")

@ds.command()
@click.pass_obj
def report(obj):
  """Print a summary of scan results."""
  results = obj.get("results", [])
  if not results:
      click.echo("No results. Run 'scan' first.")
      return
  for r in results:
      click.echo(f"{r['name']}: {r['size']} bytes")

@ds.command()
@click.option("--yes", is_flag=True)
@click.pass_obj
def clean(obj, yes):
  """Delete files from the last scan."""
  results = obj.get("results", [])
  if not results:
      click.echo("Nothing to clean.")
      return
  if not yes:
      if not click.confirm(f"Delete {len(results)} file(s)?"):
          click.echo("Aborted.")
          return
  for r in results:
      os.remove(r["path"])
      click.echo(f"Deleted {r['name']}.")
  obj["results"] = []

print("ds-tool defined.")

Test 1 — scan: happy path

Python — editable, runs in your browser

import click, os, tempfile, pathlib
from click.testing import CliRunner

@click.group()
@click.pass_context
def ds(ctx):
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv")
@click.pass_obj
def scan(obj, directory, ext):
  if not os.path.isdir(directory):
      raise click.ClickException(f"Not a directory: {directory}")
  found = []
  for entry in os.scandir(directory):
      if entry.is_file() and entry.name.endswith(ext):
          found.append({"name": entry.name, "path": entry.path, "size": entry.stat().st_size})
  obj["results"] = found
  click.echo(f"Found {len(found)} {ext} file(s) in {directory}.")

runner = CliRunner()

# --- happy path: 2 csv files ---
tmpdir = tempfile.mkdtemp()
pathlib.Path(tmpdir, "a.csv").write_text("x,y
1,2")
pathlib.Path(tmpdir, "b.csv").write_text("x,y
3,4")
pathlib.Path(tmpdir, "notes.txt").write_text("ignore me")

shared = {"results": []}
r = runner.invoke(ds, ["scan", tmpdir], obj=shared)

assert r.exit_code == 0, f"Expected 0, got {r.exit_code}: {r.output}"
assert "Found 2 .csv" in r.output
assert len(shared["results"]) == 2
print("Scan happy path: PASS")
print("Output:", r.output.strip())

# --- error path: non-existent directory ---
r2 = runner.invoke(ds, ["scan", "/nonexistent/path"], obj={"results": []})
assert r2.exit_code == 1
assert "Not a directory" in r2.output
print("Scan error path: PASS")

Test 2 — report: results and empty state

Python — editable, runs in your browser

Test 3 — clean: confirmation prompts

Python — editable, runs in your browser

import click, os, tempfile, pathlib
from click.testing import CliRunner

@click.group()
@click.pass_context
def ds(ctx):
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.option("--yes", is_flag=True)
@click.pass_obj
def clean(obj, yes):
  results = obj.get("results", [])
  if not results:
      click.echo("Nothing to clean.")
      return
  if not yes:
      if not click.confirm(f"Delete {len(results)} file(s)?"):
          click.echo("Aborted.")
          return
  for r in results:
      os.remove(r["path"])
      click.echo(f"Deleted {r['name']}.")
  obj["results"] = []

runner = CliRunner()

# --- confirm yes (via stdin) ---
tmpdir = tempfile.mkdtemp()
fpath = str(pathlib.Path(tmpdir, "a.csv"))
pathlib.Path(fpath).write_text("x")
shared = {"results": [{"name": "a.csv", "path": fpath}]}
r = runner.invoke(ds, ["clean"], input="y
", obj=shared)
assert r.exit_code == 0
assert "Deleted a.csv" in r.output
assert not os.path.exists(fpath)
print("Clean (confirm yes): PASS")

# --- confirm no (via stdin) ---
fpath2 = str(pathlib.Path(tmpdir, "b.csv"))
pathlib.Path(fpath2).write_text("x")
shared2 = {"results": [{"name": "b.csv", "path": fpath2}]}
r2 = runner.invoke(ds, ["clean"], input="n
", obj=shared2)
assert r2.exit_code == 0
assert "Aborted" in r2.output
assert os.path.exists(fpath2)
print("Clean (confirm no): PASS")

# --- --yes skips prompt ---
fpath3 = str(pathlib.Path(tmpdir, "c.csv"))
pathlib.Path(fpath3).write_text("x")
shared3 = {"results": [{"name": "c.csv", "path": fpath3}]}
r3 = runner.invoke(ds, ["clean", "--yes"], obj=shared3)
assert r3.exit_code == 0
assert "Deleted c.csv" in r3.output
print("Clean (--yes flag): PASS")

# --- nothing to clean ---
r4 = runner.invoke(ds, ["clean"], obj={"results": []})
assert r4.exit_code == 0
assert "Nothing to clean" in r4.output
print("Clean (empty results): PASS")

Test 4 — env var injection

A tool that reads DS_TOOL_DEFAULT_EXT from the environment should use that value when --ext is not provided. Test it with CliRunner's env= parameter:

Python — editable, runs in your browser

import click, os, tempfile, pathlib
from click.testing import CliRunner

# A variant of scan that reads the default extension from an env var
@click.group(context_settings={"auto_envvar_prefix": "DS_TOOL"})
@click.pass_context
def ds(ctx):
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv", help="Extension to scan for.")
@click.pass_obj
def scan(obj, directory, ext):
  found = [
      e.name for e in os.scandir(directory)
      if e.is_file() and e.name.endswith(ext)
  ]
  obj["results"] = found
  click.echo(f"Found {len(found)} {ext} file(s).")

tmpdir = tempfile.mkdtemp()
pathlib.Path(tmpdir, "data.parquet").write_text("binary")
pathlib.Path(tmpdir, "notes.csv").write_text("csv")

runner = CliRunner()

# Without env var: defaults to .csv
shared = {"results": []}
r1 = runner.invoke(ds, ["scan", tmpdir], obj=shared)
print("Default (.csv):", r1.output.strip())
assert "1 .csv" in r1.output

# With env var: DS_TOOL_EXT overrides the default
shared2 = {"results": []}
r2 = runner.invoke(ds, ["scan", tmpdir], env={"DS_TOOL_EXT": ".parquet"}, obj=shared2)
print("With DS_TOOL_EXT=.parquet:", r2.output.strip())
assert ".parquet" in r2.output
print("Env var injection: PASS")

Running pytest --cov=ds_tool tests/ after moving the tool into its own module reports per-line coverage. Aim for every branch being exercised by at least one test — not necessarily 100% line coverage, but 100% branch coverage for the CLI paths that users can reach.

What you covered

The four test sections above exercise:

Scan happy path (files found), scan error path (bad directory)
Report with results, report with empty state
Clean with stdin y, clean with stdin n, clean with --yes, clean with no results
Env var override via env=

That is every meaningful user-visible branch in ds-tool. Adding these tests before shipping means a future refactor cannot silently break the output format, the confirmation flow, or the environment-variable behaviour.

Where to go next

That completes the intermediate tier. The advanced tier covers distribution (building wheels, publishing to PyPI), writing plugins with entry points, and integrating CLIs into CI pipelines.

Finished reading? Mark it complete to track your progress.

The tool under test

Test 1 — scan: happy path

Test 2 — report: results and empty state

Test 3 — clean: confirmation prompts

Test 4 — env var injection

What you covered

Where to go next

On this page