Hands-on lab — Day 71: Why Test, and pytest Basics

"""Shared setup that pytest finds by itself.

You never import this file and nothing in the test suite mentions it by name.
pytest looks for files called `conftest.py` in the directory it is collecting
from and in every parent directory up to the rootdir, imports them before
collection starts, and makes whatever they define available to every test file
underneath them. That is the whole mechanism.

Two things live here:

* `SAMPLE`, an ordinary module-level constant the tests import by name;
* `sample_text`, a *fixture* — a function decorated with `@pytest.fixture`
  whose return value is handed to any test that names `sample_text` as a
  parameter. Fixtures are Day 72's subject. Today you only need to recognise
  one when you see it: a test parameter that is not a value but a request.
"""

import pytest

# Twelve words. Counted by hand, deliberately, because a test whose expected
# value came out of the code it is testing proves nothing at all.
#
#   the quick brown fox jumps over the lazy dog the dog barks
#    1    2     3    4    5    6    7   8    9   10  11   12
#
# Frequencies: the=3, dog=2, and one each of barks, brown, fox, jumps, lazy,
# over, quick. Total characters in words: 46, so the mean is 46/12 = 3.8333...
SAMPLE = "The quick brown fox jumps over the lazy dog. The dog barks."


@pytest.fixture
def sample_text() -> str:
    """The sample sentence, handed fresh to every test that asks for it."""
    return SAMPLE

"""Tests that live inside the documentation — `doctest`, also standard library.

Run it:

    python3 -m doctest -v examples/doctest_demo.py

`doctest` scans docstrings for lines beginning with the interactive prompt
`>>>`, runs them, and compares what comes back with the text on the following
line — character for character. The examples are documentation a reader trusts
*because* a machine checks them.

That character-for-character comparison is the whole story of doctest: it is
unbeatable for short, exact, illustrative results, and it is the wrong tool
the moment the result is long, unordered, or has a memory address in it.
"""


def initials(full_name: str) -> str:
    """Return the initials of a name, uppercased and dot-separated.

    >>> initials("ada lovelace")
    'A.L.'
    >>> initials("Grace Brewster Murray Hopper")
    'G.B.M.H.'
    >>> initials("   plato   ")
    'P.'
    >>> initials("")
    ''
    """
    parts = full_name.split()
    return "".join(part[0].upper() + "." for part in parts)


def truncate(text: str, limit: int) -> str:
    """Shorten text to at most `limit` characters, ending with a single dot.

    >>> truncate("hello", 10)
    'hello'
    >>> truncate("hello there friend", 8)
    'hello t.'
    >>> truncate("abc", 1)
    '.'

    Asking for a limit below one is a programming error, not a short string:

    >>> truncate("abc", 0)
    Traceback (most recent call last):
        ...
    ValueError: limit must be at least 1, got 0
    """
    if limit < 1:
        raise ValueError(f"limit must be at least 1, got {limit}")
    if len(text) <= limit:
        return text
    return text[: limit - 1] + "."


if __name__ == "__main__":
    import doctest

    failures, attempted = doctest.testmod(verbose=False)
    print(f"doctest: {attempted} examples attempted, {failures} failed")
    raise SystemExit(1 if failures else 0)

# This directory is a rootdir of its own, so `pytest examples/failure-demo`
# reports short paths and `pytest examples` skips it (see the `norecursedirs`
# line in examples/pytest.ini). Everything in here fails ON PURPOSE.
[pytest]
testpaths = .
addopts = -p no:cacheprovider

"""Five tests that fail on purpose, so you can read a failure report.

    pytest examples/failure-demo

Every failure here is deliberate. The point is the shape of the report: what
pytest prints when a bare `assert` is false, and how much of the comparison it
recovers for you. Compare the same five failures under `--tb=short`, `-q`,
and `-x`.
"""

import pytest


def add(a, b):
    """Deliberately wrong by one, so the arithmetic assertion fails."""
    return a + b + 1


def test_a_simple_number_comparison():
    assert add(1, 2) == 3


def test_a_list_comparison():
    expected = ["the", "cat", "sat", "on", "the", "mat"]
    actual = ["the", "cat", "sat", "on", "a", "mat"]
    assert actual == expected


def test_a_dict_comparison():
    expected = {"words": 12, "unique": 9, "mean_length": 3.83}
    actual = {"words": 12, "unique": 8, "mean_length": 3.83}
    assert actual == expected


def test_a_string_comparison():
    assert "reading time: 4 minutes" == "reading time: 3 minutes"


def test_an_exception_that_was_not_raised():
    with pytest.raises(ValueError):
        int("42")

"""The same three failures under `unittest`, for comparison.

    python3 examples/failure-demo/unittest_failure.py

Run this next to `pytest examples/failure-demo` and put the two reports side
by side. Both tell you the truth. Ask yourself how many seconds each one takes
to read.
"""

import unittest


def add(a, b):
    """Deliberately wrong by one, so the arithmetic assertion fails."""
    return a + b + 1


class ComparisonTests(unittest.TestCase):
    def test_a_simple_number_comparison(self):
        self.assertEqual(add(1, 2), 3)

    def test_a_list_comparison(self):
        expected = ["the", "cat", "sat", "on", "the", "mat"]
        actual = ["the", "cat", "sat", "on", "a", "mat"]
        self.assertEqual(actual, expected)

    def test_a_bare_assert_inside_unittest(self):
        # unittest runs a plain assert perfectly well — it just cannot tell
        # you anything about it, because nothing rewrote the statement.
        assert add(1, 2) == 3


if __name__ == "__main__":
    unittest.main()

"""A test suite with no test runner at all — just `assert`.

This is the whole idea of testing, stripped to the bone. Run it:

    python3 examples/plain_asserts.py

It prints nothing and exits 0 when everything holds. Break `textstats.py` and
it exits 1 with an AssertionError. That is already a test suite: arrange, act,
assert, and a process exit code a machine can read.

Then compare what it tells you on failure with what pytest tells you. That
difference — not the concept — is what you are paying pytest for.
"""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))

from textstats import average_word_length, top_words, word_count, words  # noqa: E402

# --- words -----------------------------------------------------------------
assert words("The cat. The hat!") == ["the", "cat", "the", "hat"]
assert words("") == []

# --- word_count ------------------------------------------------------------
assert word_count("The cat. The hat!") == 4
assert word_count("") == 0

# --- average_word_length ---------------------------------------------------
assert average_word_length("the cat") == 3.0
assert average_word_length("") == 0.0

# --- top_words -------------------------------------------------------------
assert top_words("a b a c a b", 2) == [("a", 3), ("b", 2)]
assert top_words("a b a c a b", 0) == []

print("all plain assertions held")

# The presence of this file is what makes `examples/` the rootdir when you run
# `pytest examples`. pytest walks up from the paths you gave it looking for a
# configuration file (pytest.ini, pyproject.toml, tox.ini, setup.cfg); the
# directory holding the first one it finds becomes the rootdir, and the rootdir
# is what every path in the report is printed relative to.
#
# Without this file pytest would keep walking upward and pick some ancestor
# directory you did not choose, and the report would be full of long paths.
[pytest]
testpaths = .
addopts = -p no:cacheprovider
# `failure-demo/` and `vacuous-demo/` are deliberately wrong, so a plain
# `pytest examples` must not walk into them. Run each one deliberately:
#   pytest examples/failure-demo   ·   pytest examples/vacuous-demo
norecursedirs = failure-demo vacuous-demo

"""The worked reference suite for `textstats`.

Every test below is arrange, act, assert — usually in exactly three lines, and
often in one when the arrangement is a literal. Read them as sentences: the
name says what should be true, the body proves it.

Run it:

    pytest examples

Nothing here imports pytest except the two tests that need `pytest.raises` and
`pytest.approx`, and nothing here inherits from anything. A test is a plain
function whose name starts with `test_`.
"""

import pytest

from conftest import SAMPLE
from textstats import (
    average_word_length,
    reading_time_minutes,
    top_words,
    word_count,
    words,
)

# --------------------------------------------------------------------------
# words() — the tokeniser everything else is built on
# --------------------------------------------------------------------------


def test_words_splits_on_punctuation_and_lowercases():
    assert words("The cat. The hat!") == ["the", "cat", "the", "hat"]


def test_words_keeps_an_apostrophe_inside_a_word():
    assert words("don't stop") == ["don't", "stop"]


def test_words_of_empty_text_is_empty():
    assert words("") == []


def test_words_ignores_digits_and_symbols():
    assert words("3 apples & 4 pears") == ["apples", "pears"]


# --------------------------------------------------------------------------
# word_count()
# --------------------------------------------------------------------------


def test_word_count_of_the_sample_is_twelve(sample_text):
    assert word_count(sample_text) == 12


def test_word_count_of_empty_text_is_zero():
    assert word_count("") == 0


# --------------------------------------------------------------------------
# average_word_length()
# --------------------------------------------------------------------------


def test_average_word_length_of_two_equal_words():
    # "the" and "cat" are three characters each, so the mean is exactly 3.0.
    assert average_word_length("the cat") == 3.0


def test_average_word_length_of_the_sample(sample_text):
    # 46 characters over 12 words is 3.8333..., rounded to 3.83.
    assert average_word_length(sample_text) == pytest.approx(3.83)


def test_average_word_length_of_empty_text_is_zero():
    # The bug this catches: the original divided by len(found) with no words.
    assert average_word_length("") == 0.0


# --------------------------------------------------------------------------
# top_words() — grouped in a class purely to show that pytest collects
# `Test*` classes too. No base class, no setUp, no self-management.
# --------------------------------------------------------------------------


class TestTopWords:
    def test_returns_exactly_n_items(self):
        # The bug this catches: the original sliced to n - 1.
        assert top_words("a b a c a b", 2) == [("a", 3), ("b", 2)]

    def test_orders_by_frequency_then_alphabetically(self, sample_text):
        assert top_words(sample_text, 3) == [("the", 3), ("dog", 2), ("barks", 1)]

    def test_asking_for_more_than_exist_returns_everything(self):
        assert top_words("a b a c a b", 9) == [("a", 3), ("b", 2), ("c", 1)]

    def test_asking_for_zero_returns_nothing(self):
        assert top_words("a b a c a b", 0) == []

    def test_empty_text_has_no_top_words(self):
        assert top_words("", 5) == []


# --------------------------------------------------------------------------
# reading_time_minutes()
# --------------------------------------------------------------------------


def test_reading_time_rounds_up_to_a_whole_minute():
    assert reading_time_minutes("hello there") == 1


def test_reading_time_of_five_hundred_words_at_two_hundred_a_minute():
    # 500 / 200 is 2.5, and reading time always rounds up.
    assert reading_time_minutes("word " * 500) == 3


def test_reading_time_honours_a_slower_speed():
    assert reading_time_minutes("word " * 500, 100) == 5


def test_reading_time_of_empty_text_is_zero():
    assert reading_time_minutes("") == 0


def test_reading_time_rejects_a_non_positive_speed():
    with pytest.raises(ValueError, match="must be positive"):
        reading_time_minutes(SAMPLE, 0)

"""Small text statistics helpers — the FIXED reference module.

This is `starter/textstats.py` with its two bugs repaired. Two functions
differ, and both repairs are marked below with the comment `# repaired`.
Compare the two files once you have found the bugs yourself:

    diff starter/textstats.py examples/textstats.py

The docstrings are unchanged, because the docstrings were never wrong — the
code was. That is the usual shape of a bug: the specification was fine and
somebody's fingers were not.
"""

from __future__ import annotations

import math
import re

# A "word" is a run of letters, optionally containing apostrophes, so that
# "don't" is one word and "state-of-the-art" is four.
WORD_PATTERN = re.compile(r"[A-Za-z']+")


def words(text: str) -> list[str]:
    """Split text into lowercase words.

    Punctuation and digits are separators. The result is in reading order and
    may contain repeats.

        words("The cat. The hat!") -> ['the', 'cat', 'the', 'hat']
        words("")                  -> []
    """
    return [match.group(0).lower() for match in WORD_PATTERN.finditer(text)]


def word_count(text: str) -> int:
    """Count the words in text.

        word_count("The cat. The hat!") -> 4
        word_count("")                  -> 0
    """
    return len(words(text))


def average_word_length(text: str) -> float:
    """Mean number of characters per word, rounded to two decimal places.

    Empty text has no words, so the average is defined to be 0.0 — asking for
    the mean of nothing is not an error, it is just nothing.

        average_word_length("the cat")  -> 3.0
        average_word_length("")         -> 0.0
    """
    found = words(text)
    if not found:  # repaired: the mean of no words is 0.0, not a crash
        return 0.0
    total_characters = sum(len(word) for word in found)
    return round(total_characters / len(found), 2)


def top_words(text: str, n: int) -> list[tuple[str, int]]:
    """The n most frequent words, most frequent first.

    Ties are broken alphabetically so the result is deterministic. Asking for
    more words than exist returns everything. Asking for zero returns nothing.

        top_words("a b a c a b", 2) -> [('a', 3), ('b', 2)]
        top_words("a b a c a b", 9) -> [('a', 3), ('b', 2), ('c', 1)]
        top_words("a b a c a b", 0) -> []
    """
    counts: dict[str, int] = {}
    for word in words(text):
        counts[word] = counts.get(word, 0) + 1
    ranked = sorted(counts.items(), key=lambda pair: (-pair[1], pair[0]))
    return ranked[:n]  # repaired: a slice already stops before index n


def reading_time_minutes(text: str, words_per_minute: int = 200) -> int:
    """Whole minutes needed to read text, always rounded up.

    Any text at all takes at least one minute; empty text takes none. The
    reading speed must be a positive number of words per minute.

        reading_time_minutes("hello there")            -> 1
        reading_time_minutes("word " * 500)            -> 3
        reading_time_minutes("word " * 500, 100)       -> 5
        reading_time_minutes("")                       -> 0
    """
    if words_per_minute <= 0:
        raise ValueError(f"words_per_minute must be positive, got {words_per_minute}")
    return math.ceil(word_count(text) / words_per_minute)

"""The same tests written with `unittest`, which ships with Python.

Run it:

    python3 examples/unittest_demo.py -v

Nothing to install. Notice the three costs pytest removes: you inherit from
`unittest.TestCase`, you call a differently-named method for every kind of
comparison (`assertEqual`, `assertAlmostEqual`, `assertRaises`, `assertIn`,
`assertTrue`), and the boilerplate at the bottom exists so the file can be run
directly.

Notice also what `unittest` gives you for free that is genuinely good: it is
in the standard library, so a suite written this way runs on any machine with
Python and no network at all.
"""

import sys
import unittest
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))

from textstats import (  # noqa: E402
    average_word_length,
    reading_time_minutes,
    top_words,
    word_count,
    words,
)

SAMPLE = "The quick brown fox jumps over the lazy dog. The dog barks."


class TextStatsTests(unittest.TestCase):
    def test_words_splits_on_punctuation_and_lowercases(self):
        self.assertEqual(words("The cat. The hat!"), ["the", "cat", "the", "hat"])

    def test_word_count_of_the_sample(self):
        self.assertEqual(word_count(SAMPLE), 12)

    def test_average_word_length_of_empty_text(self):
        self.assertEqual(average_word_length(""), 0.0)

    def test_average_word_length_of_the_sample(self):
        self.assertAlmostEqual(average_word_length(SAMPLE), 3.83, places=2)

    def test_top_words_returns_exactly_n_items(self):
        self.assertEqual(top_words("a b a c a b", 2), [("a", 3), ("b", 2)])

    def test_reading_time_rejects_a_non_positive_speed(self):
        with self.assertRaises(ValueError):
            reading_time_minutes(SAMPLE, 0)


if __name__ == "__main__":
    unittest.main()

#!/usr/bin/env bash
# Prove that four of the five tests next door are worthless.
#
#   bash examples/vacuous-demo/prove_it.sh
#
# It copies this directory to a temporary one, breaks `top_words` with a
# single sed, and runs the suite twice: once with only the four vacuous tests
# selected, once with the honest one. The first stays green on broken code.
# The second does not. Nothing in your working tree is modified.
set -u

here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
lab_dir="$(cd "${here}/../.." && pwd)"

resolve_tool() {
  local tool="$1" override="$2"
  if [ -n "${override}" ] && [ -x "${override}" ]; then echo "${override}"; return 0; fi
  if [ -x "${lab_dir}/.venv/bin/${tool}" ]; then echo "${lab_dir}/.venv/bin/${tool}"; return 0; fi
  if command -v "${tool}" >/dev/null 2>&1; then command -v "${tool}"; return 0; fi
  return 1
}

pytest_bin="$(resolve_tool pytest "${PYTEST:-}")" || {
  echo "FAIL: pytest not found. See requirements/README.md." >&2
  exit 1
}

work="$(mktemp -d "${TMPDIR:-/tmp}/vacuous.XXXXXX")"
cp "${here}/textstats.py" "${here}/test_vacuous.py" "${here}/pytest.ini" "${work}/"

echo "Breaking top_words: ranked[:n] becomes ranked[: n - 1]"
sed -i.bak 's/return ranked\[:n\].*/return ranked[: n - 1]/' "${work}/textstats.py"
rm -f "${work}/textstats.py.bak"
echo

echo "--- the four vacuous tests, on the BROKEN module ---"
(cd "${work}" && "${pytest_bin}" . -q -k "not exactly_two_items")
vacuous_exit=$?
echo "exit: ${vacuous_exit}"
echo

echo "--- the one honest test, on the same BROKEN module ---"
(cd "${work}" && "${pytest_bin}" . -q -k "exactly_two_items" --tb=short)
honest_exit=$?
echo "exit: ${honest_exit}"
echo

rm -rf "${work}"

if [ "${vacuous_exit}" -eq 0 ] && [ "${honest_exit}" -ne 0 ]; then
  echo "Point made: four green tests, one broken function, zero warnings."
  exit 0
fi
echo "Unexpected: the demonstration did not behave as described." >&2
exit 1

# A rootdir of its own, so `pytest examples/vacuous-demo` reports short paths
# and `pytest examples` skips it. This directory exists to be wrong.
[pytest]
testpaths = .
addopts = -p no:cacheprovider

"""Four tests that pass no matter what the code does.

    pytest examples/vacuous-demo -v

All four are green. All four are worthless. Prove it with the script next to
this file, which breaks `top_words` and re-runs them:

    bash examples/vacuous-demo/prove_it.sh

The suite stays green. That is the failure mode this whole lab exists to make
visible: a green suite is a claim, and an untested claim is a lie you tell
yourself every morning at nine.

The fifth test at the bottom is the same intent written properly. It is the
only one that notices.
"""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))

from textstats import top_words, word_count  # noqa: E402

TEXT = "a b a c a b"


def test_top_words_returns_something():
    # A list is a list. This would pass if the function returned garbage.
    assert top_words(TEXT, 2) is not None


def test_top_words_returns_a_list():
    # Still true of the wrong list.
    assert isinstance(top_words(TEXT, 2), list)


def test_top_words_does_not_crash():
    # "It ran" is not a specification.
    top_words(TEXT, 2)
    assert True


def test_word_count_is_not_negative():
    # A count is never negative whatever the bug, so this can never fail.
    assert word_count(TEXT) >= 0


def test_top_words_returns_exactly_two_items_in_the_right_order():
    # The same intent, written so it can fail. This is the only test here
    # that would tell you the truth.
    assert top_words(TEXT, 2) == [("a", 3), ("b", 2)]

"""Small text statistics helpers — the FIXED reference module.

This is `starter/textstats.py` with its two bugs repaired. Two functions
differ, and both repairs are marked below with the comment `# repaired`.
Compare the two files once you have found the bugs yourself:

    diff starter/textstats.py examples/textstats.py

The docstrings are unchanged, because the docstrings were never wrong — the
code was. That is the usual shape of a bug: the specification was fine and
somebody's fingers were not.
"""

from __future__ import annotations

import math
import re

# A "word" is a run of letters, optionally containing apostrophes, so that
# "don't" is one word and "state-of-the-art" is four.
WORD_PATTERN = re.compile(r"[A-Za-z']+")


def words(text: str) -> list[str]:
    """Split text into lowercase words.

    Punctuation and digits are separators. The result is in reading order and
    may contain repeats.

        words("The cat. The hat!") -> ['the', 'cat', 'the', 'hat']
        words("")                  -> []
    """
    return [match.group(0).lower() for match in WORD_PATTERN.finditer(text)]


def word_count(text: str) -> int:
    """Count the words in text.

        word_count("The cat. The hat!") -> 4
        word_count("")                  -> 0
    """
    return len(words(text))


def average_word_length(text: str) -> float:
    """Mean number of characters per word, rounded to two decimal places.

    Empty text has no words, so the average is defined to be 0.0 — asking for
    the mean of nothing is not an error, it is just nothing.

        average_word_length("the cat")  -> 3.0
        average_word_length("")         -> 0.0
    """
    found = words(text)
    if not found:  # repaired: the mean of no words is 0.0, not a crash
        return 0.0
    total_characters = sum(len(word) for word in found)
    return round(total_characters / len(found), 2)


def top_words(text: str, n: int) -> list[tuple[str, int]]:
    """The n most frequent words, most frequent first.

    Ties are broken alphabetically so the result is deterministic. Asking for
    more words than exist returns everything. Asking for zero returns nothing.

        top_words("a b a c a b", 2) -> [('a', 3), ('b', 2)]
        top_words("a b a c a b", 9) -> [('a', 3), ('b', 2), ('c', 1)]
        top_words("a b a c a b", 0) -> []
    """
    counts: dict[str, int] = {}
    for word in words(text):
        counts[word] = counts.get(word, 0) + 1
    ranked = sorted(counts.items(), key=lambda pair: (-pair[1], pair[0]))
    return ranked[:n]  # repaired: a slice already stops before index n


def reading_time_minutes(text: str, words_per_minute: int = 200) -> int:
    """Whole minutes needed to read text, always rounded up.

    Any text at all takes at least one minute; empty text takes none. The
    reading speed must be a positive number of words per minute.

        reading_time_minutes("hello there")            -> 1
        reading_time_minutes("word " * 500)            -> 3
        reading_time_minutes("word " * 500, 100)       -> 5
        reading_time_minutes("")                       -> 0
    """
    if words_per_minute <= 0:
        raise ValueError(f"words_per_minute must be positive, got {words_per_minute}")
    return math.ceil(word_count(text) / words_per_minute)

lesson_id: D071
day: 71
kind: python-program
languages: [python, bash]
setup_commands:
  - cd labs/sections/programming-with-python/day-071-why-test-and-pytest-basics
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
  - .venv/bin/pytest --version
run_commands:
  - .venv/bin/pytest examples
  - .venv/bin/pytest examples -q
  - .venv/bin/pytest examples --collect-only -q
  - .venv/bin/pytest examples -k reading_time
  - .venv/bin/pytest examples/failure-demo
  - .venv/bin/pytest examples/failure-demo -x --tb=short
  - bash examples/vacuous-demo/prove_it.sh
  - python3 examples/plain_asserts.py
  - python3 examples/unittest_demo.py -v
  - python3 examples/doctest_demo.py
  - .venv/bin/pytest starter -v
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'find . -type d -name __pycache__ -prune -exec rm -rf -- {} +'
  - 'rm -rf .venv  # optional: removes the installed pytest'
  - 'git checkout -- starter/  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-19'
executed_on: 'macOS 26.5.1 (Apple Silicon), Python 3.14.0, pytest 9.1.1, bash 3.2.57 — bash tests/run_tests.sh -> 47 checks, 0 failure(s), exit 0'

# Dependencies — Day 071 lab

This is the first lab in the course with a `requirements.txt`. Everything from
Day 43 to Day 70 ran on the standard library alone. Week 11 is *about* tools,
so this week the tools are the point.

## What is pinned

```text
pytest==9.1.1
```

One package, one exact version.

| Package | Version | Licence | What it is | Why this lab needs it |
| --- | --- | --- | --- | --- |
| pytest | 9.1.1 | MIT | A test runner: it finds your tests, runs them, and reports what failed | The whole lab is about reading its output and trusting its exit code |

The licence is not taken on trust. After installing, ask the package itself:

```bash
.venv/bin/pip show pytest
```

On the authoring machine that reports `Version: 9.1.1`,
`License-Expression: MIT`, and
`Requires: iniconfig, packaging, pluggy, pygments`.

The version is exact — `==`, not `>=`. A pinned version is why the captured
output in `expected-output/` matches what you see. Test-tool output changes
between releases, and a lab that says "you will see 19 passed" has to name the
version that says it.

## Why nothing else

Installing pytest also pulls in four small libraries it depends on —
`iniconfig` (reading `pytest.ini`), `packaging` (version comparisons),
`pluggy` (the plugin system) and `pygments` (syntax colouring in reports).
That is the whole tree; there is no framework underneath. Everything else this
lab uses — `unittest`, `doctest`, `re`, `math` — ships with Python.
The two standard-library runners are demonstrated deliberately: if you ever
land somewhere you cannot install a package, you can still write and run tests
that day.

## Free and open source

pytest is free and open source under the MIT licence, with no paid tier, no
account, and no telemetry. Installing it downloads from the Python Package
Index. That download is the only moment in this lab that touches the network;
once installed, every command runs fully offline.

## The one-time install

You met `python3 -m venv` on Day 43. Same idea, one directory per lab, so this
lab's pytest cannot collide with anything else on your machine:

```bash
cd labs/sections/programming-with-python/day-071-why-test-and-pytest-basics
python3 -m venv .venv
.venv/bin/pip install -r requirements/requirements.txt
.venv/bin/pytest --version
```

The last command should print `pytest 9.1.1`.

`.venv/` is ignored by version control repository-wide. Never commit it: it is
a build artifact, it is large, and it is specific to your machine and Python
version.

## Running without a lab-local virtual environment

If you already have pytest 9.x somewhere — a system install, a shared
environment, an activated venv — you do not need a second copy. The test
runner resolves the tool in three steps: an explicit override, then this lab's
`.venv/bin/pytest`, then whatever `pytest` is on `PATH`. So both of these work:

```bash
bash tests/run_tests.sh                         # uses .venv or PATH
PYTEST=/path/to/pytest bash tests/run_tests.sh  # uses exactly what you name
```

If none of the three finds a pytest, the runner stops with the install
instructions rather than quietly reporting success on nothing — a test suite
that skips itself and exits 0 is the exact failure this lab teaches you to
distrust.

## Checking your Python

```bash
python3 --version
```

pytest 9.1.1 needs Python 3.9 or newer; this lab was authored and executed on
Python 3.14.0. Windows users: run everything inside WSL, or substitute
`.venv\Scripts\pytest` for `.venv/bin/pytest` and use `python` for `python3`.

## What Week 11 adds later

Day 075 adds `mypy` to this file and Day 076 adds `ruff`, so by Day 077 the
pinned set is three lines. All three are free and open source. Nothing else
gets added: a testing setup that needs a page of dependencies is a testing
setup nobody will run.

pytest==9.1.1

"""Shared setup that pytest finds by itself.

You never import this file and nothing in the test suite mentions it by name.
pytest looks for files called `conftest.py` in the directory it is collecting
from and in every parent directory up to the rootdir, imports them before
collection starts, and makes whatever they define available to every test file
underneath them. That is the whole mechanism.

Two things live here:

* `SAMPLE`, an ordinary module-level constant the tests import by name;
* `sample_text`, a *fixture* — a function decorated with `@pytest.fixture`
  whose return value is handed to any test that names `sample_text` as a
  parameter. Fixtures are Day 72's subject. Today you only need to recognise
  one when you see it: a test parameter that is not a value but a request.
"""

import pytest

# Twelve words. Counted by hand, deliberately, because a test whose expected
# value came out of the code it is testing proves nothing at all.
#
#   the quick brown fox jumps over the lazy dog the dog barks
#    1    2     3    4    5    6    7   8    9   10  11   12
#
# Frequencies: the=3, dog=2, and one each of barks, brown, fox, jumps, lazy,
# over, quick. Total characters in words: 46, so the mean is 46/12 = 3.8333...
SAMPLE = "The quick brown fox jumps over the lazy dog. The dog barks."


@pytest.fixture
def sample_text() -> str:
    """The sample sentence, handed fresh to every test that asks for it."""
    return SAMPLE

# The presence of this file is what makes `starter/` the rootdir when you run
# `pytest starter`. pytest walks up from the paths you gave it looking for a
# configuration file (pytest.ini, pyproject.toml, tox.ini, setup.cfg); the
# directory holding the first one it finds becomes the rootdir, and the rootdir
# is what every path in the report is printed relative to.
#
# Without this file pytest would keep walking upward and pick some ancestor
# directory you did not choose, and the report would be full of long paths.
[pytest]
testpaths = .
addopts = -p no:cacheprovider

"""YOUR test suite for `textstats`. Eight numbered exercises.

Run it from the lab directory, not from here:

    pytest starter -v

Exercise 1 is finished, so the file runs the moment you open it. Exercises 2
to 7 each end in a `pytest.skip(...)` line: pytest reports them as `s` in the
dot line and moves on, so an unfinished suite still exits 0. Replace the skip
line with real assertions as you go — deleting the skip is part of the
exercise.

Two of these tests are supposed to FAIL when you first write them correctly.
That is not you making a mistake; that is the suite doing its job on a module
with two real bugs in it. Exercise 8 is where you fix the module.

The specification you are testing against is the docstrings in `textstats.py`.
Read them. Do not read the implementation to decide what the answer should be
— if you copy the expected value out of the code, your test agrees with the
bug and proves nothing.
"""

import pytest

from conftest import SAMPLE
from textstats import (
    average_word_length,
    reading_time_minutes,
    top_words,
    word_count,
    words,
)


# --------------------------------------------------------------------------
# EXERCISE 1 (worked for you) — the shape of every test in this file.
#
# Arrange: build the inputs.        Act: call the thing.        Assert: state
# what must be true. Here the arrangement is a literal, so it fits in one
# line, which is normal and good.
#
# Run just this one:   pytest starter -v -k splits_on_punctuation
# --------------------------------------------------------------------------


def test_words_splits_on_punctuation_and_lowercases():
    assert words("The cat. The hat!") == ["the", "cat", "the", "hat"]


# --------------------------------------------------------------------------
# EXERCISE 2 — the empty case, for `words`.
#
# The docstring says `words("")` is `[]`. Assert exactly that, then delete the
# skip line below. Check with:   pytest starter -v -k empty
# --------------------------------------------------------------------------


def test_words_of_empty_text_is_empty():
    pytest.skip("exercise 2: assert that words('') equals [], then delete this line")


# --------------------------------------------------------------------------
# EXERCISE 3 — count the sample.
#
# `sample_text` as a parameter asks pytest for the fixture defined in
# `conftest.py`; it arrives as the sentence itself. Its word count is written
# down in `conftest.py`, counted by hand. Assert `word_count(sample_text)`
# equals that number. Check with:   pytest starter -v -k word_count
# --------------------------------------------------------------------------


def test_word_count_of_the_sample(sample_text):
    pytest.skip("exercise 3: assert the hand-counted word count, then delete this line")


# --------------------------------------------------------------------------
# EXERCISE 4 — the first bug.
#
# The docstring of `average_word_length` says empty text gives 0.0. Assert it.
# This test is EXPECTED TO FAIL against the module as shipped. Read the
# failure report carefully — it names the exception, the line, and the call
# that produced it. Check with:   pytest starter -v -k average
# --------------------------------------------------------------------------


def test_average_word_length_of_empty_text_is_zero():
    pytest.skip("exercise 4: assert average_word_length('') == 0.0, then delete this line")


# --------------------------------------------------------------------------
# EXERCISE 5 — a value you can verify by hand.
#
# "the cat" is two words of three characters, so the mean is exactly 3.0.
# Assert that. Then add a second assertion for the sample sentence, whose mean
# is 46 characters over 12 words. Because that is 3.8333... you need
# `pytest.approx(3.83)` rather than `== 3.83` — floating-point equality is a
# trap you have already met on Day 70.
# --------------------------------------------------------------------------


def test_average_word_length_of_known_text(sample_text):
    pytest.skip("exercise 5: assert 3.0 for 'the cat' and approx(3.83) for the sample")


# --------------------------------------------------------------------------
# EXERCISE 6 — the second bug, inside a class.
#
# pytest collects classes named `Test*` and their `test_*` methods. There is
# no base class and no setUp; `self` is there only because Python methods take
# it. Fill in all four methods from the `top_words` docstring:
#
#   top_words("a b a c a b", 2) -> [('a', 3), ('b', 2)]
#   top_words("a b a c a b", 9) -> [('a', 3), ('b', 2), ('c', 1)]
#   top_words("a b a c a b", 0) -> []
#   top_words("", 5)            -> []
#
# At least one of these is EXPECTED TO FAIL. Check with:
#   pytest starter -v -k TestTopWords
# --------------------------------------------------------------------------


class TestTopWords:
    def test_returns_exactly_n_items(self):
        pytest.skip("exercise 6a: assert the two-item result, then delete this line")

    def test_asking_for_more_than_exist_returns_everything(self):
        pytest.skip("exercise 6b: assert all three items come back")

    def test_asking_for_zero_returns_nothing(self):
        pytest.skip("exercise 6c: assert the result is []")

    def test_empty_text_has_no_top_words(self):
        pytest.skip("exercise 6d: assert the result is []")


# --------------------------------------------------------------------------
# EXERCISE 7 — an expected exception.
#
# `reading_time_minutes` raises `ValueError` when the speed is not positive.
# Asserting that a call raises is done with a context manager:
#
#   with pytest.raises(ValueError, match="must be positive"):
#       reading_time_minutes(SAMPLE, 0)
#
# The `match=` argument is a regular expression checked against the message,
# so the test fails if the right exception is raised for the wrong reason.
# Write that test, and add three more covering the rounding rules from the
# docstring: "hello there" -> 1, "word " * 500 -> 3, and "" -> 0.
# --------------------------------------------------------------------------


def test_reading_time_rules():
    pytest.skip("exercise 7: assert the rounding rules and the ValueError")


# --------------------------------------------------------------------------
# EXERCISE 8 — go green.
#
# With exercises 2 to 7 written, run:   pytest starter -v
# You should see failures from exercise 4 and from exercise 6. Now fix
# `starter/textstats.py` — two lines, one in each broken function — and run
# again until every test passes and the process exits 0:
#
#   pytest starter -q
#   echo $?
#
# Then prove your suite is not vacuous. Re-break one of the two lines, run
# again, and confirm the exit code is 1. A suite that stays green when the
# code is wrong is worse than no suite, because it is a promise you are not
# keeping.
#
# Finally, add ONE more test of your own for a case none of the above covers.
# Name it `test_...` and make it fail first, on purpose, before you make it
# pass.
# --------------------------------------------------------------------------

"""Small text statistics helpers — the module under test.

This module works. Mostly. It was written quickly, checked by eye on one
paragraph of English prose, and shipped. Two of its five public functions are
wrong, and neither is wrong in a way you notice by reading the code once.

Your job in this lab is NOT to read this file until you spot the bugs. Your
job is to write tests that catch them. Read the docstrings — they are the
specification. Then write tests that hold the code to the docstrings.

Do not edit this file until exercise 8 tells you to.
"""

from __future__ import annotations

import math
import re

# A "word" is a run of letters, optionally containing apostrophes, so that
# "don't" is one word and "state-of-the-art" is four.
WORD_PATTERN = re.compile(r"[A-Za-z']+")


def words(text: str) -> list[str]:
    """Split text into lowercase words.

    Punctuation and digits are separators. The result is in reading order and
    may contain repeats.

        words("The cat. The hat!") -> ['the', 'cat', 'the', 'hat']
        words("")                  -> []
    """
    return [match.group(0).lower() for match in WORD_PATTERN.finditer(text)]


def word_count(text: str) -> int:
    """Count the words in text.

        word_count("The cat. The hat!") -> 4
        word_count("")                  -> 0
    """
    return len(words(text))


def average_word_length(text: str) -> float:
    """Mean number of characters per word, rounded to two decimal places.

    Empty text has no words, so the average is defined to be 0.0 — asking for
    the mean of nothing is not an error, it is just nothing.

        average_word_length("the cat")  -> 3.0
        average_word_length("")         -> 0.0
    """
    found = words(text)
    total_characters = sum(len(word) for word in found)
    return round(total_characters / len(found), 2)


def top_words(text: str, n: int) -> list[tuple[str, int]]:
    """The n most frequent words, most frequent first.

    Ties are broken alphabetically so the result is deterministic. Asking for
    more words than exist returns everything. Asking for zero returns nothing.

        top_words("a b a c a b", 2) -> [('a', 3), ('b', 2)]
        top_words("a b a c a b", 9) -> [('a', 3), ('b', 2), ('c', 1)]
        top_words("a b a c a b", 0) -> []
    """
    counts: dict[str, int] = {}
    for word in words(text):
        counts[word] = counts.get(word, 0) + 1
    ranked = sorted(counts.items(), key=lambda pair: (-pair[1], pair[0]))
    return ranked[: n - 1]


def reading_time_minutes(text: str, words_per_minute: int = 200) -> int:
    """Whole minutes needed to read text, always rounded up.

    Any text at all takes at least one minute; empty text takes none. The
    reading speed must be a positive number of words per minute.

        reading_time_minutes("hello there")            -> 1
        reading_time_minutes("word " * 500)            -> 3
        reading_time_minutes("word " * 500, 100)       -> 5
        reading_time_minutes("")                       -> 0
    """
    if words_per_minute <= 0:
        raise ValueError(f"words_per_minute must be positive, got {words_per_minute}")
    return math.ceil(word_count(text) / words_per_minute)

#!/usr/bin/env bash
# Tests for the Day 071 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# This suite is unusual: it is a test suite ABOUT a test suite. Its job is to
# prove that the pytest suite in examples/ is not decorative. Three of the
# checks below do that directly, and they are the ones worth reading:
#
#   * "a broken implementation makes the suite fail" copies the fixed module
#     to a temporary directory, breaks exactly one line with sed, and asserts
#     that pytest exits NON-ZERO. A suite that stays green when the code is
#     wrong is worse than no suite at all;
#   * "the reference suite catches both shipped bugs" runs the reference tests
#     against the buggy starter module and asserts it fails on precisely the
#     two functions that are wrong;
#   * "an empty directory exits 5" pins pytest's own exit-code contract, which
#     is the thing continuous integration actually reads.
#
# No network, non-interactive, deterministic. Exits 0 only if every check
# passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# Resolve pytest: an explicit override, then this lab's .venv, then whatever
# is on PATH. Fails loudly with instructions rather than silently skipping.
resolve_tool() {
  local tool="$1" override="$2"
  if [ -n "${override}" ] && [ -x "${override}" ]; then echo "${override}"; return 0; fi
  if [ -x "${lab_dir}/.venv/bin/${tool}" ]; then echo "${lab_dir}/.venv/bin/${tool}"; return 0; fi
  if command -v "${tool}" >/dev/null 2>&1; then command -v "${tool}"; return 0; fi
  return 1
}

pytest_bin="$(resolve_tool pytest "${PYTEST:-}")" || {
  echo "FAIL: pytest not found." >&2
  echo "  Install it with:" >&2
  echo "    python3 -m venv .venv" >&2
  echo "    .venv/bin/pip install -r requirements/requirements.txt" >&2
  echo "  Or point this suite at an existing pytest: PYTEST=/path/to/pytest bash tests/run_tests.sh" >&2
  exit 1
}

python_bin="$(command -v python3 || true)"
if [ -z "${python_bin}" ]; then
  echo "FAIL: python3 not found on PATH." >&2
  exit 1
fi

echo "Day 071 — Your First Real Test Suite"
echo

# --------------------------------------------------------------------------
echo "1. The tool itself"
# --------------------------------------------------------------------------

version_line="$("${pytest_bin}" --version 2>&1 | head -1)"
case "${version_line}" in
  pytest*) check "pytest --version reports a pytest ( ${version_line} )" "yes" ;;
  *) check "pytest --version reports a pytest ( ${version_line} )" "no" ;;
esac

# --------------------------------------------------------------------------
echo
echo "2. The reference suite passes"
# --------------------------------------------------------------------------

examples_out="$(cd "${lab_dir}" && "${pytest_bin}" examples -q 2>&1)"
examples_exit=$?
if [ "${examples_exit}" -eq 0 ]; then
  check "pytest examples exits 0" "yes"
else
  check "pytest examples exits 0 (got ${examples_exit})" "no"
  echo "${examples_out}" | tail -20
fi

case "${examples_out}" in
  *"19 passed"*) check "pytest examples reports 19 passed" "yes" ;;
  *) check "pytest examples reports 19 passed" "no" ;;
esac

# --------------------------------------------------------------------------
echo
echo "3. Collection: rootdir, test ids, and selection"
# --------------------------------------------------------------------------

collected="$(cd "${lab_dir}" && "${pytest_bin}" examples --collect-only -q 2>&1)"

for test_id in \
  "test_textstats.py::test_words_of_empty_text_is_empty" \
  "test_textstats.py::test_average_word_length_of_empty_text_is_zero" \
  "test_textstats.py::TestTopWords::test_returns_exactly_n_items" \
  "test_textstats.py::test_reading_time_rejects_a_non_positive_speed"
do
  case "${collected}" in
    *"${test_id}"*) check "collection finds ${test_id}" "yes" ;;
    *) check "collection finds ${test_id}" "no" ;;
  esac
done

case "${collected}" in
  *"19 tests collected"*) check "collection finds exactly 19 tests" "yes" ;;
  *) check "collection finds exactly 19 tests" "no" ;;
esac

# `Test*` classes are collected too, and their ids carry the class name.
class_ids="$(printf '%s\n' "${collected}" | grep -c '::TestTopWords::' || true)"
if [ "${class_ids}" -eq 5 ]; then
  check "the TestTopWords class contributes 5 collected tests" "yes"
else
  check "the TestTopWords class contributes 5 collected tests (got ${class_ids})" "no"
fi

selected="$(cd "${lab_dir}" && "${pytest_bin}" examples -q -k "top_words or TestTopWords" 2>&1)"
case "${selected}" in
  *"5 passed, 14 deselected"*) check "-k 'top_words or TestTopWords' selects 5 of 19" "yes" ;;
  *) check "-k 'top_words or TestTopWords' selects 5 of 19" "no" ;;
esac

reading_selected="$(cd "${lab_dir}" && "${pytest_bin}" examples -q -k "reading_time" 2>&1)"
case "${reading_selected}" in
  *"5 passed, 14 deselected"*) check "-k reading_time selects the 5 reading-time tests" "yes" ;;
  *) check "-k reading_time selects the 5 reading-time tests" "no" ;;
esac

# --------------------------------------------------------------------------
echo
echo "4. Failure reporting and assertion rewriting"
# --------------------------------------------------------------------------

failure_out="$(cd "${lab_dir}" && "${pytest_bin}" examples/failure-demo 2>&1)"
failure_exit=$?
if [ "${failure_exit}" -eq 1 ]; then
  check "the deliberate-failure demo exits 1" "yes"
else
  check "the deliberate-failure demo exits 1 (got ${failure_exit})" "no"
fi

case "${failure_out}" in
  *"assert 4 == 3"*) check "assertion rewriting shows both sides: 'assert 4 == 3'" "yes" ;;
  *) check "assertion rewriting shows both sides: 'assert 4 == 3'" "no" ;;
esac

case "${failure_out}" in
  *"where 4 = add(1, 2)"*) check "the report explains where the 4 came from" "yes" ;;
  *) check "the report explains where the 4 came from" "no" ;;
esac

case "${failure_out}" in
  *"At index 4 diff:"*) check "a list mismatch names the index that differs" "yes" ;;
  *) check "a list mismatch names the index that differs" "no" ;;
esac

case "${failure_out}" in
  *"DID NOT RAISE ValueError"*) check "pytest.raises reports a missing exception" "yes" ;;
  *) check "pytest.raises reports a missing exception" "no" ;;
esac

case "${failure_out}" in
  *"short test summary info"*) check "the short test summary lists every failure" "yes" ;;
  *) check "the short test summary lists every failure" "no" ;;
esac

stop_first="$(cd "${lab_dir}" && "${pytest_bin}" examples/failure-demo -x -q --tb=short 2>&1)"
case "${stop_first}" in
  *"1 failed"*) check "-x stops after the first failure" "yes" ;;
  *) check "-x stops after the first failure" "no" ;;
esac

# --------------------------------------------------------------------------
echo
echo "5. Exit codes — the contract continuous integration reads"
# --------------------------------------------------------------------------

empty_dir="$(mktemp -d "${TMPDIR:-/tmp}/pytest-empty.XXXXXX")"
(cd "${empty_dir}" && "${pytest_bin}" . -q >/dev/null 2>&1)
empty_exit=$?
rm -rf "${empty_dir}"
if [ "${empty_exit}" -eq 5 ]; then
  check "a run that collects no tests exits 5, not 0" "yes"
else
  check "a run that collects no tests exits 5, not 0 (got ${empty_exit})" "no"
fi

# --------------------------------------------------------------------------
echo
echo "6. The suite actually tests something (the checks that matter)"
# --------------------------------------------------------------------------

# 6a. Control: the fixed module plus the reference suite is green.
work="$(mktemp -d "${TMPDIR:-/tmp}/pytest-break.XXXXXX")"
cp "${lab_dir}/examples/textstats.py" "${lab_dir}/examples/test_textstats.py" \
   "${lab_dir}/examples/conftest.py" "${lab_dir}/examples/pytest.ini" "${work}/"
(cd "${work}" && "${pytest_bin}" . -q >/dev/null 2>&1)
control_exit=$?
if [ "${control_exit}" -eq 0 ]; then
  check "control: the fixed module passes the reference suite (exit 0)" "yes"
else
  check "control: the fixed module passes the reference suite (got ${control_exit})" "no"
fi

# 6b. Break exactly one line and demand a non-zero exit.
sed -i.bak 's/return len(words(text))/return len(words(text)) + 1/' "${work}/textstats.py"
rm -f "${work}/textstats.py.bak"
if grep -q 'return len(words(text)) + 1' "${work}/textstats.py"; then
  check "the sed edit really changed word_count" "yes"
else
  check "the sed edit really changed word_count" "no"
fi
broken_out="$(cd "${work}" && "${pytest_bin}" . -q 2>&1)"
broken_exit=$?
if [ "${broken_exit}" -ne 0 ]; then
  check "a one-line break makes the suite FAIL (exit ${broken_exit}, not 0)" "yes"
else
  check "a one-line break makes the suite FAIL — it did not, so the suite is vacuous" "no"
fi
case "${broken_out}" in
  *"test_word_count_of_the_sample_is_twelve"*)
    check "the failing run names test_word_count_of_the_sample_is_twelve" "yes" ;;
  *) check "the failing run names test_word_count_of_the_sample_is_twelve" "no" ;;
esac
rm -rf "${work}"

# 6c. The reference suite catches both bugs shipped in starter/textstats.py.
buggy="$(mktemp -d "${TMPDIR:-/tmp}/pytest-buggy.XXXXXX")"
cp "${lab_dir}/starter/textstats.py" "${buggy}/"
cp "${lab_dir}/examples/test_textstats.py" "${lab_dir}/examples/conftest.py" \
   "${lab_dir}/examples/pytest.ini" "${buggy}/"
buggy_out="$(cd "${buggy}" && "${pytest_bin}" . -q 2>&1)"
buggy_exit=$?
if [ "${buggy_exit}" -ne 0 ]; then
  check "the reference suite rejects the buggy starter module" "yes"
else
  check "the reference suite rejects the buggy starter module" "no"
fi
case "${buggy_out}" in
  *"test_average_word_length_of_empty_text_is_zero"*)
    check "bug 1 caught: average_word_length divides by zero on empty text" "yes" ;;
  *) check "bug 1 caught: average_word_length divides by zero on empty text" "no" ;;
esac
case "${buggy_out}" in
  *"TestTopWords::test_returns_exactly_n_items"*)
    check "bug 2 caught: top_words is off by one" "yes" ;;
  *) check "bug 2 caught: top_words is off by one" "no" ;;
esac
case "${buggy_out}" in
  *"4 failed, 15 passed"*)
    check "exactly 4 of the 19 reference tests fail on the buggy module" "yes" ;;
  *) check "exactly 4 of the 19 reference tests fail on the buggy module" "no" ;;
esac
rm -rf "${buggy}"

# 6d. The two repairs are exactly where the lesson says they are, and the
#     starter really does still carry both bugs.
if grep -q 'return ranked\[: n - 1\]' "${lab_dir}/starter/textstats.py"; then
  check "starter/textstats.py still carries the off-by-one slice" "yes"
else
  check "starter/textstats.py still carries the off-by-one slice" "no"
fi
if grep -q 'return ranked\[:n\]' "${lab_dir}/examples/textstats.py"; then
  check "examples/textstats.py repairs the slice to ranked[:n]" "yes"
else
  check "examples/textstats.py repairs the slice to ranked[:n]" "no"
fi
if grep -q 'if not found:' "${lab_dir}/examples/textstats.py"; then
  check "examples/textstats.py guards the empty-text division" "yes"
else
  check "examples/textstats.py guards the empty-text division" "no"
fi
if grep -q 'if not found:' "${lab_dir}/starter/textstats.py"; then
  check "starter/textstats.py still lacks the empty-text guard" "no"
else
  check "starter/textstats.py still lacks the empty-text guard" "yes"
fi

# 6e. The vacuous-test demonstration behaves exactly as the lesson claims:
#     four green tests on a knowingly broken function, and one honest test
#     that catches it. prove_it.sh exits 0 only if both halves hold.
if (cd "${lab_dir}" && PYTEST="${pytest_bin}" bash examples/vacuous-demo/prove_it.sh >/dev/null 2>&1); then
  check "four vacuous tests stay green on broken code; the honest one fails" "yes"
else
  check "four vacuous tests stay green on broken code; the honest one fails" "no"
fi

vacuous_out="$(cd "${lab_dir}" && "${pytest_bin}" examples/vacuous-demo -q 2>&1)"
case "${vacuous_out}" in
  *"5 passed"*) check "all 5 vacuous-demo tests pass on the CORRECT module" "yes" ;;
  *) check "all 5 vacuous-demo tests pass on the CORRECT module" "no" ;;
esac

# `pytest examples` must not wander into either deliberately-wrong directory.
case "${examples_out}" in
  *vacuous*|*failure*) check "norecursedirs keeps the wrong-on-purpose dirs out of 'pytest examples'" "no" ;;
  *) check "norecursedirs keeps the wrong-on-purpose dirs out of 'pytest examples'" "yes" ;;
esac

# --------------------------------------------------------------------------
echo
echo "7. The starter is runnable before you start"
# --------------------------------------------------------------------------

starter_out="$(cd "${lab_dir}" && "${pytest_bin}" starter -q 2>&1)"
starter_exit=$?
if [ "${starter_exit}" -eq 0 ]; then
  check "pytest starter exits 0 with the exercises unfinished" "yes"
else
  check "pytest starter exits 0 with the exercises unfinished (got ${starter_exit})" "no"
fi
case "${starter_out}" in
  *"1 passed, 9 skipped"*) check "the starter has 1 worked test and 9 skipped exercises" "yes" ;;
  *) check "the starter has 1 worked test and 9 skipped exercises" "no" ;;
esac

starter_collected="$(cd "${lab_dir}" && "${pytest_bin}" starter --collect-only -q 2>&1)"
case "${starter_collected}" in
  *"10 tests collected"*) check "the starter collects 10 tests" "yes" ;;
  *) check "the starter collects 10 tests" "no" ;;
esac

# --------------------------------------------------------------------------
echo
echo "8. Testing without pytest: assert, unittest, doctest"
# --------------------------------------------------------------------------

if (cd "${lab_dir}" && "${python_bin}" examples/plain_asserts.py >/dev/null 2>&1); then
  check "examples/plain_asserts.py exits 0 — bare asserts are already a suite" "yes"
else
  check "examples/plain_asserts.py exits 0 — bare asserts are already a suite" "no"
fi

# The same file, with the module broken, must exit non-zero.
plain="$(mktemp -d "${TMPDIR:-/tmp}/plain-assert.XXXXXX")"
cp "${lab_dir}/examples/textstats.py" "${lab_dir}/examples/plain_asserts.py" "${plain}/"
sed -i.bak 's/return len(words(text))/return len(words(text)) + 1/' "${plain}/textstats.py"
rm -f "${plain}/textstats.py.bak"
if (cd "${plain}" && "${python_bin}" plain_asserts.py >/dev/null 2>&1); then
  check "a broken module makes the bare-assert script exit non-zero" "no"
else
  check "a broken module makes the bare-assert script exit non-zero" "yes"
fi
rm -rf "${plain}"

if (cd "${lab_dir}" && "${python_bin}" examples/unittest_demo.py >/dev/null 2>&1); then
  check "examples/unittest_demo.py passes under the stdlib runner" "yes"
else
  check "examples/unittest_demo.py passes under the stdlib runner" "no"
fi

unittest_fail_out="$(cd "${lab_dir}" && "${python_bin}" examples/failure-demo/unittest_failure.py 2>&1)"
unittest_fail_exit=$?
if [ "${unittest_fail_exit}" -ne 0 ]; then
  check "the unittest failure demo exits non-zero" "yes"
else
  check "the unittest failure demo exits non-zero" "no"
fi
case "${unittest_fail_out}" in
  *"AssertionError: 4 != 3"*)
    check "unittest's assertEqual reports both sides" "yes" ;;
  *) check "unittest's assertEqual reports both sides" "no" ;;
esac
# The bare assert inside unittest gets NO values — nothing rewrote it.
if printf '%s\n' "${unittest_fail_out}" \
   | grep -A2 'test_a_bare_assert_inside_unittest' >/dev/null 2>&1; then
  bare_detail="$(printf '%s\n' "${unittest_fail_out}" | grep -c '^AssertionError$' || true)"
  if [ "${bare_detail}" -ge 1 ]; then
    check "a bare assert under unittest reports no values at all" "yes"
  else
    check "a bare assert under unittest reports no values at all" "no"
  fi
else
  check "a bare assert under unittest reports no values at all" "no"
fi

doctest_out="$(cd "${lab_dir}" && "${python_bin}" examples/doctest_demo.py 2>&1)"
doctest_exit=$?
if [ "${doctest_exit}" -eq 0 ]; then
  check "examples/doctest_demo.py exits 0" "yes"
else
  check "examples/doctest_demo.py exits 0" "no"
fi
case "${doctest_out}" in
  *"8 examples attempted, 0 failed"*) check "doctest runs all 8 documented examples" "yes" ;;
  *) check "doctest runs all 8 documented examples (got: ${doctest_out})" "no" ;;
esac

if (cd "${lab_dir}" && "${python_bin}" -m doctest examples/doctest_demo.py >/dev/null 2>&1); then
  check "python3 -m doctest agrees, and says nothing when all is well" "yes"
else
  check "python3 -m doctest agrees, and says nothing when all is well" "no"
fi

# --------------------------------------------------------------------------
echo
echo "9. Nothing here touches the network or the clock"
# --------------------------------------------------------------------------

if grep -rqE 'import (socket|urllib|requests|http)|datetime\.now|time\.time|random\.' \
     "${lab_dir}/examples" "${lab_dir}/starter" 2>/dev/null; then
  check "no network, clock or randomness in examples/ or starter/" "no"
else
  check "no network, clock or randomness in examples/ or starter/" "yes"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]