Expects: Expressive TDD/BDD Assertion Library

Common errors

• NameError: name 'expect' is not defined

  cause The `expect` callable was not imported into the current scope.
  fix Add `from expects import *` or `from expects import expect` at the top of your test file.

• IndentationError: expected an indented block

  cause This usually occurs when copy-pasting code, and Python's strict indentation rules are violated.
  fix Ensure consistent indentation (typically 4 spaces) throughout your Python code, especially after colons for code blocks (e.g., function definitions, `if` statements).

• TypeError: 'Matcher' object is not callable

  cause Attempting to call a matcher directly (e.g., `expect(value).to(be_empty())` instead of `expect(value).to(be_empty)`). Matchers are properties, not functions, when used with `.to()`.
  fix Remove the parentheses when using matchers with `.to()`, unless the matcher explicitly expects arguments (e.g., `equal(5)`). Correct: `expect(value).to(be_empty)`.

Warnings

• gotcha The primary recommended import, `from expects import *`, pollutes the global namespace with `expect` and all matcher functions (e.g., `equal`, `be_empty`). While convenient for small tests, this can lead to name collisions in larger codebases.
  Fix: For larger projects, consider importing `expect` and specific matchers explicitly: `from expects import expect, equal, be_empty`.
• gotcha The `expects` library has not seen a new release since October 2018 (version 0.9.0). While functional, it might not be actively maintained, which could lead to compatibility issues with newer Python versions, lack of bug fixes for modern environments, or unaddressed security vulnerabilities.
  Fix: Review the GitHub repository for any unreleased changes or forks. For critical projects, consider alternative, more actively maintained assertion libraries if future Python compatibility is a concern.
• gotcha Despite its 2018 release date, version 0.9.0 of `expects` explicitly states compatibility with Python 2.7. However, mixing Python 2 and 3 environments with libraries released around the 2.x to 3.x transition (e.9., some `0.9.0` releases like `cmd2` v0.9.0) has historically led to `pip` installing incorrect versions. Verify your Python interpreter version and `expects` installation if encountering unexpected behavior, especially in older Python 2.7 environments.
  Fix: Ensure you are using a Python 3.x environment (3.4+ is recommended by the library itself) for the most stable experience. If sticking with Python 2.7, explicitly pin `expects<0.9.0` or test thoroughly.

Install

• pip install expects Install stable version

Imports

• expect
  wrong:

  import expects
  expects.expect([])

  correct:

  from expects import expect, be_empty, equal

  The primary usage pattern is to import 'expect' and specific matchers, or use 'from expects import *' for convenience, as 'expects.expect' is not the intended API.
• * (all matchers)

  from expects import *

  Commonly used for quick setup to bring 'expect' and all built-in matchers into the global namespace.

Quickstart

This quickstart demonstrates basic usage of `expect` and several built-in matchers like `equal`, `be_empty`, `not_to`, `raise_error`, and `have_key`. It showcases how to write expressive assertions for common testing scenarios.

from expects import *

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

# Example assertions
expect(5).to(equal(5))
expect([]).to(be_empty)
expect(False).not_to(be_true)
expect(lambda: divide(1, 0)).to(raise_error(ValueError, 'Cannot divide by zero'))
expect({'name': 'Alice'}).to(have_key('name'))

print("All assertions passed!")