Skip to main content

Discovers and runs unit tests with a single-word command.

Project description


Easy-to-use unit test runner.

  • Simplifies discovery of unittest.TestCase tests in the project
  • Runs tests with standard unittest
  • Testing can be started from the shell with a single-word command: neatest
  • Testing can be customized by python scripts calling

neatest can replace many runs of python -m unittest discover ... command. The priority for neatest is full compatibility and interchangeability with the standard unittest. Tests that can be run from neatest can also be run with unittest without any project modification.

Supports Python 3.7+ on Linux, macOS and Windows.


pip3 install neatest

Project layout

neatest discovers all classes inherited from unittest.TestCase within the project. Test cases can be placed in any .py file inside any directory. If you prefer to keep test cases in the "tests" directory with filenames starting with "test", they will be discovered, because they are also "any files in any directory".

You can use a simple project layout:

my_simple_project     # tests can be placed here       # tests can be placed here       # tests can be placed here     # tests can be placed here

or a project with multiple packages:

    package_a         # tests can be placed here        # tests can be placed here      # tests can be placed here     # tests can be placed here
    package_b         # tests can be placed here
    tests          # tests can be placed here   # tests can be placed here    # tests can be placed here        

Subdirectories must be importable as packages from the project directory.

They are importable, when you can

$ cd my_complex_project
$ python3 

and then in Python

import package_a
import package_b
import tests 


Run tests from command line

$ cd my_complex_project
$ neatest
Package "package_a" contains 3 tests
Package "package_b" contains 4 tests
Package "tests" contains 16 tests
Ran 23 tests in 2.947s


Add some options:

$ cd my_complex_project
$ neatest --start-directory tests --verbose

See all possible options:

$ neatest --help

Run tests from .py script

Create a script

For example,

import neatest

Run the script

$ cd my_complex_project
$ python3 path/to/

The idea is to use single .py script to run the tests (instead of .sh, .bat or .cfg). Python scripts are readable, and they are portable as the Python itself.

You can specify all the options available to neatest command-line tool as arguments to method:

import neatest"tests",



You can specify dependencies to be installed with pip install before testing. These dependencies are presumably missing from requirements.txt and as they are not needed in production.['requests', 'lxml']) 
$ neatest -r requests -r lxml

This is the equivalent of the deprecated argument tests_require from setuptools.setup.


By default, warnings caught during testing are printed to the stdout.

warnings: ignore

In this mode warnings will not be displayed.
$ neatest --warnings ignore

warnings: fail

In this mode warnings will be treated as errors. If at least one warning appears during testing, it will cause the testing to fail (with exception or non-zero return code).
$ neatest --warnings fail

Test discovery


neatest searches for tests in all *.py files.

The same can be achieved with standard unittest like this:

$ python3 -m unittest discover -p "*.py"


neatest assumes, that the current directory is the project directory. It is the base directory for all imports.

If the start_directory are not specified, neatest will find all the packages inside the project directory and will run tests for each of them.

    package_a               # tests in package_a will be discovered
    package_b               # tests in package_b will be discovered
    package_c               # tests in package_c will be discovered
        subpackage          # subpackage is a part of package_c 
       # so tests will be discovered
    subdir                  # subdir is not a package
        package_d           # tests in package_d will NOT be discovered  
       # because package_d is not importable

So the commands

$ cd my_project
$ neatest

will run the same tests as

$ cd my_project
$ python3 -m unittest discover -t . -s package_a -p "*.py"
$ python3 -m unittest discover -t . -s package_b -p "*.py"
$ python3 -m unittest discover -t . -s package_c -p "*.py"

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neatest-3.9.1.tar.gz (10.4 kB view hashes)

Uploaded source

Built Distribution

neatest-3.9.1-py3-none-any.whl (9.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page