Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


Documentation Status

Read better test failures.


marbles is a Python unittest extension that allows test authors to write richer tests that expose more information on test failure to help you debug failing tests faster.

  • Treat test failures as documentation
  • Contextualize failures without digging through test code and dropping debugging statements everywhere
  • Write clearer, more explicit tests


  • Drop-in unittest replacement
  • Information-rich failure messages
    • The full statement that failed (instead of just the last line)
    • Local variables in scope at the time the test failed
    • Optional annotation provided by the test author with details about the test
    • Ability to toggle traceback
  • Semantically-rich assertion methods
  • Assertion logging


You can run the example tests provided to see what a marbles failure message looks like


You can also run your existing unittest tests with marbles

python -m marbles

Marbles also creates a setuptools command so if you are used to running python test, you can now run:

python marbles

You can go one step further and alias the command test to run marbles by adding the following to setup.cfg:

test = marbles


pip install marbles