# unittest-parallel
[](https://pypi.org/project/unittest-parallel/)
[](https://pypi.org/project/unittest-parallel/)
[](https://github.com/craigahobbs/unittest-parallel/blob/main/LICENSE)
[](https://pypi.org/project/unittest-parallel/)
unittest-parallel is a parallel unit test runner for Python with coverage support.
## Run Unit Tests in Parallel
To run unittest-parallel, specify the directory containing your unit tests with the `-s` argument
and your package's top-level directory using the `-t` argument:
~~~
unittest-parallel -t . -s tests
~~~
By default, unittest-parallel runs unit test modules on all CPU cores available.
To run your unit tests with coverage, add either the `--coverage` option (for line coverage) or the
`--coverage-branch` for line and branch coverage.
~~~
unittest-parallel -t . -s tests --coverage-branch
~~~
## Parallelism Level
By default, unittest-parallel runs test modules in parallel, which works with
[test class and module fixtures](https://docs.python.org/3/library/unittest.html#class-and-module-fixtures).
If you don't have any module fixtures, you can use the `--level=class` option to run test classes in
parallel. If you don't have any module or class fixtures, you can use the `--level=test` option to
run individual tests in parallel.
## Do I Need unittest-parallel?
unittest-parallel helps the most when you have many long-running unit tests, such as those that make
web service calls or are compute-intensive. If you just have many fast-running unit tests,
unittest-parallel may slow down unit test execution due to the cost of parallelization.
For example, for one of my projects with thousands of long-running unit tests, running tests with
unittest-parallel is **five times faster** than running tests using Python's built-in unit test
runner.
For another project, with hundreds of fast-running unit tests, running tests using unittest-parallel
is **twice as slow** as running them using Python's built-in unit test runner.
To determine if unittest-parallel will improve your unit test run times, you'll need to try it on
your project.
## Usage
~~~
usage: unittest-parallel [-h] [-v] [-q] [-f] [-b] [-k TESTNAMEPATTERNS]
[-s START] [-p PATTERN] [-t TOP] [--runner RUNNER]
[--result RESULT] [-j COUNT]
[--level {module,class,test}]
[--disable-process-pooling] [--coverage]
[--coverage-branch] [--coverage-rcfile RCFILE]
[--coverage-include PAT] [--coverage-omit PAT]
[--coverage-source SRC] [--coverage-html DIR]
[--coverage-xml FILE] [--coverage-fail-under MIN]
options:
-h, --help show this help message and exit
-v, --verbose Verbose output
-q, --quiet Quiet output
-f, --failfast Stop on first fail or error
-b, --buffer Buffer stdout and stderr during tests
-k TESTNAMEPATTERNS Only run tests which match the given substring
-s, --start-directory START
Directory to start discovery ('.' default)
-p, --pattern PATTERN
Pattern to match tests ('test*.py' default)
-t, --top-level-directory TOP
Top level directory of project (defaults to start
directory)
--runner RUNNER Custom unittest runner class <module>.<class>
--result RESULT Custom unittest result class <module>.<class>
parallelization options:
-j, --jobs COUNT The number of test processes (default is 0, all cores)
--level {module,class,test}
Set the test parallelism level (default is 'module')
--disable-process-pooling
Do not reuse processes used to run test suites
coverage options:
--coverage Run tests with coverage
--coverage-branch Run tests with branch coverage
--coverage-rcfile RCFILE
Specify coverage configuration file
--coverage-include PAT
Include only files matching one of these patterns.
Accepts shell-style (quoted) wildcards.
--coverage-omit PAT Omit files matching one of these patterns. Accepts
shell-style (quoted) wildcards.
--coverage-source SRC
A list of packages or directories of code to be
measured
--coverage-html DIR Generate coverage HTML report
--coverage-xml FILE Generate coverage XML report
--coverage-fail-under MIN
Fail if coverage percentage under min
~~~
## Development
This package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).
It was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:
~~~
template-specialize python-template/template/ unittest-parallel/ -k package unittest-parallel -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapi 1
~~~
Raw data
{
"_id": null,
"home_page": "https://github.com/craigahobbs/unittest-parallel",
"name": "unittest-parallel",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "test, unittest, coverage, parallel",
"author": "Craig A. Hobbs",
"author_email": "craigahobbs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/21/e7/1909145ef39e95037ea250c3a677ee43979c5fb78b13d908e23d75b0a189/unittest_parallel-1.7.1.tar.gz",
"platform": null,
"description": "# unittest-parallel\n\n[](https://pypi.org/project/unittest-parallel/)\n[](https://pypi.org/project/unittest-parallel/)\n[](https://github.com/craigahobbs/unittest-parallel/blob/main/LICENSE)\n[](https://pypi.org/project/unittest-parallel/)\n\nunittest-parallel is a parallel unit test runner for Python with coverage support.\n\n\n## Run Unit Tests in Parallel\n\nTo run unittest-parallel, specify the directory containing your unit tests with the `-s` argument\nand your package's top-level directory using the `-t` argument:\n\n~~~\nunittest-parallel -t . -s tests\n~~~\n\nBy default, unittest-parallel runs unit test modules on all CPU cores available.\n\nTo run your unit tests with coverage, add either the `--coverage` option (for line coverage) or the\n`--coverage-branch` for line and branch coverage.\n\n~~~\nunittest-parallel -t . -s tests --coverage-branch\n~~~\n\n\n## Parallelism Level\n\nBy default, unittest-parallel runs test modules in parallel, which works with\n[test class and module fixtures](https://docs.python.org/3/library/unittest.html#class-and-module-fixtures).\nIf you don't have any module fixtures, you can use the `--level=class` option to run test classes in\nparallel. If you don't have any module or class fixtures, you can use the `--level=test` option to\nrun individual tests in parallel.\n\n\n## Do I Need unittest-parallel?\n\nunittest-parallel helps the most when you have many long-running unit tests, such as those that make\nweb service calls or are compute-intensive. If you just have many fast-running unit tests,\nunittest-parallel may slow down unit test execution due to the cost of parallelization.\n\nFor example, for one of my projects with thousands of long-running unit tests, running tests with\nunittest-parallel is **five times faster** than running tests using Python's built-in unit test\nrunner.\n\nFor another project, with hundreds of fast-running unit tests, running tests using unittest-parallel\nis **twice as slow** as running them using Python's built-in unit test runner.\n\nTo determine if unittest-parallel will improve your unit test run times, you'll need to try it on\nyour project.\n\n\n## Usage\n\n~~~\nusage: unittest-parallel [-h] [-v] [-q] [-f] [-b] [-k TESTNAMEPATTERNS]\n [-s START] [-p PATTERN] [-t TOP] [--runner RUNNER]\n [--result RESULT] [-j COUNT]\n [--level {module,class,test}]\n [--disable-process-pooling] [--coverage]\n [--coverage-branch] [--coverage-rcfile RCFILE]\n [--coverage-include PAT] [--coverage-omit PAT]\n [--coverage-source SRC] [--coverage-html DIR]\n [--coverage-xml FILE] [--coverage-fail-under MIN]\n\noptions:\n -h, --help show this help message and exit\n -v, --verbose Verbose output\n -q, --quiet Quiet output\n -f, --failfast Stop on first fail or error\n -b, --buffer Buffer stdout and stderr during tests\n -k TESTNAMEPATTERNS Only run tests which match the given substring\n -s, --start-directory START\n Directory to start discovery ('.' default)\n -p, --pattern PATTERN\n Pattern to match tests ('test*.py' default)\n -t, --top-level-directory TOP\n Top level directory of project (defaults to start\n directory)\n --runner RUNNER Custom unittest runner class <module>.<class>\n --result RESULT Custom unittest result class <module>.<class>\n\nparallelization options:\n -j, --jobs COUNT The number of test processes (default is 0, all cores)\n --level {module,class,test}\n Set the test parallelism level (default is 'module')\n --disable-process-pooling\n Do not reuse processes used to run test suites\n\ncoverage options:\n --coverage Run tests with coverage\n --coverage-branch Run tests with branch coverage\n --coverage-rcfile RCFILE\n Specify coverage configuration file\n --coverage-include PAT\n Include only files matching one of these patterns.\n Accepts shell-style (quoted) wildcards.\n --coverage-omit PAT Omit files matching one of these patterns. Accepts\n shell-style (quoted) wildcards.\n --coverage-source SRC\n A list of packages or directories of code to be\n measured\n --coverage-html DIR Generate coverage HTML report\n --coverage-xml FILE Generate coverage XML report\n --coverage-fail-under MIN\n Fail if coverage percentage under min\n~~~\n\n\n## Development\n\nThis package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).\nIt was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:\n\n~~~\ntemplate-specialize python-template/template/ unittest-parallel/ -k package unittest-parallel -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapi 1\n~~~\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parallel unit test runner with coverage support",
"version": "1.7.1",
"project_urls": {
"Homepage": "https://github.com/craigahobbs/unittest-parallel"
},
"split_keywords": [
"test",
" unittest",
" coverage",
" parallel"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fcd1a98bbb890aeeeebf0ff1b8b84023de06a931d3c51675d7c8aa658e483902",
"md5": "ac6ffcd66f811421f2eae33270220b2c",
"sha256": "0eece465f436957fe425a721ba08527c6b27c876ee1b1178f2436131da3d65e9"
},
"downloads": -1,
"filename": "unittest_parallel-1.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac6ffcd66f811421f2eae33270220b2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8926,
"upload_time": "2024-12-18T17:03:44",
"upload_time_iso_8601": "2024-12-18T17:03:44.133828Z",
"url": "https://files.pythonhosted.org/packages/fc/d1/a98bbb890aeeeebf0ff1b8b84023de06a931d3c51675d7c8aa658e483902/unittest_parallel-1.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21e71909145ef39e95037ea250c3a677ee43979c5fb78b13d908e23d75b0a189",
"md5": "fb8f2224077c9753bf1566742fbde363",
"sha256": "832b51b8a5b48cb7fa271f15f9e06cec02ec751629c1e0646c90f70a2edbb517"
},
"downloads": -1,
"filename": "unittest_parallel-1.7.1.tar.gz",
"has_sig": false,
"md5_digest": "fb8f2224077c9753bf1566742fbde363",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9327,
"upload_time": "2024-12-18T17:03:46",
"upload_time_iso_8601": "2024-12-18T17:03:46.441011Z",
"url": "https://files.pythonhosted.org/packages/21/e7/1909145ef39e95037ea250c3a677ee43979c5fb78b13d908e23d75b0a189/unittest_parallel-1.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 17:03:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "craigahobbs",
"github_project": "unittest-parallel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "unittest-parallel"
}
JSON
