Generate a thorough unit test suite for one function

Write unit tests for the function below, using [TEST FRAMEWORK, E.G. PYTEST, JEST, JUNIT].

Before writing any test code, list the behaviors you intend to cover as a short table: input class → expected outcome. Include:
- the documented happy path(s)
- boundary values for every numeric, string-length, or collection-size parameter
- empty, null, and wrong-shape inputs, with the expected error behavior
- every branch visible in the code (each if/else, early return, exception path)

Then write the tests. Rules:
- One behavior per test; the test name states the behavior in plain words.
- No test may depend on another test's side effects or on execution order.
- Mock only true externals (network, clock, filesystem, database) — never the function under test or pure helpers it calls.
- If a behavior cannot be tested without refactoring (hidden dependency, static call, hardcoded time), do not skip it silently: write the test as it should look and add a one-line note naming the missing seam.
- Use realistic literal values, not "foo"/"bar", when the domain is clear from names or types.

After the tests, list any behaviors you deliberately did not cover and why, so I can decide whether they matter.

Function under test:
[PASTE FUNCTION AND ANY TYPES OR HELPERS IT REFERENCES]