Green is a clean, colorful test runner for Python unit tests. Compare it tonose or trial.

Green grew out of a desire to see pretty colors. Really! A big part of thewhole the **Red/Green/Refactor** process in test-driven-development is_actually getting to see red and green output_. Most python unit testingactually goes **Gray/Gray/Refactor** (at least on my terminal, which is graytext on black background). That's a shame. Even TV is in color these days.Why not terminal output? Even worse, the default output for most test runnersis cluttered, hard-to-read, redundant, and the dang statuses are not alignedvertically! Green fixes all that.

The simplest way is to just run `green your_project_dir` in the parentdirectory of your project. (For convenience, you can also use `greenX` or`greenX.Y`, where `X` and `Y` are the major and minor version number of yourPython installation.)

If your tests are extremely simple (don't attempt absolute imports), or if youcarefully set up your `PYTHONPATH` environment variable to include the parentpath of your project, you may be able to just run `green` from _inside_ yourproject directory.

By default, Green mimics the verbosity levels of vanilla unittest or nose,meaning that output is mostly just dots. For Green we recommend adding moreverbosity by using the `-v` or `-vv` options.

To run Green's own internal unit tests (which are hopefully all passing):

green -v green

To see all examples of all the failures, errors, etc. that could occur:

green -v green.examples

Advanced Usage--------------

Please see `green --help`

Install-------

Replace `pip3` with your version of pip if necessary. You may need to prependthis command with `sudo` or run it as root if your normal user cannot write tothe local Python package directory.

pip3 install green

Upgrade-------

pip3 install --upgrade green

Wait...what do I have installed?

green --version

Uninstall---------

pip3 uninstall green

Unit Test Structure Tutorial----------------------------

This tutorial *does* cover:

- External structure of your project (directory and file layout)- Skeleton of a real test module- How to import stuff from from your project into your test module- Gotchas about naming...everything.- Where to run green from and what the output could look like.

This tutorial *does not* cover:

- Stupid, useless examples like _all-your-code-and-tests-in-one-file_.- [Why you should write unit tests at all](http://stackoverflow.com/questions/67299/is-unit-testing-worth-the-effort)- The benefits of [Test-Driven Development](http://en.wikipedia.org/wiki/Test-driven_development)- How to use the [unittest](https://docs.python.org/library/unittest.html) module.- How to write [good](http://stackoverflow.com/questions/61400/what-makes-a-good-unit-test) unit tests.

### External Structure ###

This is what your project layout should look like with just one module in yourpackage:

```python# Import stuff you need for the unit tests themselves to workimport unittest

# Import stuff that you want to test. Don't import extra stuff if you don't# have to.from proj.foo import answer, School

# If you need the whole module, you can do this:# from proj import foo## Here's another reasonable way to import the whole module:# import proj.foo as foo## In either case, you would obviously need to access objects like this:# foo.answer()# foo.School()

3. What a test class and/or its methods _actually test_ is entirely up to you. In some sense it is an artform. Just use the test classes to group a bunch of methods that seem logical to go together.

4. The methods of `TestAnswer` have docstrings, while the methods on `TestSchool` do not. For most output modes, green will use the methoddocstring to describe the test if it is present, and the name of the method ifit is not. Notice the difference in the output below.

### Running Green ###

To run the unittests, we would change to the parent directory of the project(`/home/user` in this example) and then run `green proj`.

**In a real terminal, this output is syntax highlighted**

$ green proj .... Ran 4 tests in 0.000s

OK (passes=4)

Okay, so that's the classic short-form output for unit tests. Green reallyshines when you start getting more verbose:

4. Green always outputs a summary of statuses that will add up to the total number of tests that were run. For some reason, many test runners forget about statuses other than Error and Fail, and even the built-in unittest runner forgets about passing ones.