# Welcome to nose2

nose2’s extends `unittest` to make testing nicer.

## nose2 vs nose

`nose2` originated as the successor to `nose`.

`nose2` is a distinct project and does not support all of the behaviors of `nose`. See differences for a thorough rundown.

## nose2 vs pytest

pytest is an excellent test framework and we encourage users to consider it for new projects.

It has a bigger team of maintainers and a larger community of users.

## Quickstart

Because `nose2` is based on unittest, you can start from the Python Standard Library’s documentation for unittest and then use nose2 to add value on top of that.

`nose2` looks for tests in Python files whose names start with `test` and runs every test function it discovers.

Here’s an example of a simple test, written in typical unittest style:

    # in test_simple.py
    import unittest

    class TestStrings(unittest.TestCase):
        def test_upper(self):
            self.assertEqual("spam".upper(), "SPAM")

You can then run this test like so:

    $ nose2 -v
    test_upper (test_simple.TestStrings) ... ok

    ----------------------------------------------------------------------
    Ran 1 test in 0.000s

    OK

However, `nose2` supports more testing configuration and provides more tools than `unittest` on its own.

For example, this test exercises just a few of `nose2`’s features:

    # in test_fancy.py
    from nose2.tools import params

    @params("Sir Bedevere", "Miss Islington", "Duck")
    def test_is_knight(value):
        assert value.startswith('Sir')

and then run this like so:

    $ nose2 -v --pretty-assert
    test_fancy.test_is_knight:1
    'Sir Bedevere' ... ok
    test_fancy.test_is_knight:2
    'Miss Islington' ... FAIL
    test_fancy.test_is_knight:3
    'Duck' ... FAIL

    ======================================================================
    FAIL: test_fancy.test_is_knight:2
    'Miss Islington'
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/mnt/ebs/home/sirosen/tmp/test_fancy.py", line 6, in test_is_knight
        assert value.startswith('Sir')
    AssertionError

    >>> assert value.startswith('Sir')

    values:
        value = 'Miss Islington'
        value.startswith = <built-in method startswith of str object at 0x7f3c3172f430>
    ======================================================================
    FAIL: test_fancy.test_is_knight:3
    'Duck'
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/mnt/ebs/home/sirosen/tmp/test_fancy.py", line 6, in test_is_knight
        assert value.startswith('Sir')
    AssertionError

    >>> assert value.startswith('Sir')

    values:
        value = 'Duck'
        value.startswith = <built-in method startswith of str object at 0x7f3c3172d490>
    ----------------------------------------------------------------------
    Ran 3 tests in 0.001s

    FAILED (failures=2)

## Full Docs

Full documentation for `nose2` is available at docs.nose2.io

## Versions and Support

### Changelog and Version Scheme

nose2 versions are numbered `0.MAJOR.MINOR`. Minor releases contain bugfixes or smaller features. Major features or backwards incompatible changes are done in major releases.

For a full description of all past versions and changes, see the changelog.

### Python Versions

nose2 requires Python 3.

It supports all versions currently supported by the CPython team, and also aims to support PyPy and cpython betas.

#### Python 2

Python 2 is no longer supported. The 0.12.x line of releases contains the last versions which supported Python 2.

Users of Python 2 should understand that Python 2 is EOL and the Python 2 support line for `nose2` is similarly considered EOL.

Note

Fixes to 0.12.x may still be accepted on an as-needed basis for a short while as the python3-only line of releases gets started.

## Contributing

If you want to make contributions, please read the contributing guide.

# User’s Guide

- Getting started with nose2
  - Installation
  - Running tests
- Using nose2
  - Naming Tests
  - Running Tests
  - Getting Help
- Configuring nose2
  - Configuration Files
  - Configuring Plugins
  - Test Runner Tips and Tweaks
- Differences: nose2 vs nose vs unittest2
  - nose2 is not nose
  - nose2 is not (exactly) unittest2/plugins
- Plugins for nose2
  - Built in and Loaded by Default
  - Built in but not Loaded by Default
  - Third-party Plugins
- Tools and Helpers
  - Tools for Test Authors
- Changelog
  - Unreleased
  - 0.15.1 (2024-05-31)
  - 0.15.0 (2024-05-30)
  - 0.14.2 (2024-05-07)
  - 0.14.1 (2024-01-28)
  - 0.14.0 (2023-10-04)
  - 0.13.0 (2023-04-29)
  - 0.12.0 (2022-07-16)
  - 0.11.0 (2022-02-12)
  - 0.10.0 (2021-01-27)
  - 0.9.2 (2020-02-02)
  - 0.9.1 (2019-04-02)
  - 0.9.0 (2019-03-17)
  - 0.8.0 (2018-07-31)
  - 0.7.4 (2018-02-17)
  - 0.7.3 (2017-12-13)
  - 0.7.2 (2017-11-14)
  - 0.7.0 (2017-11-05)
  - 0.6.5 (2016-06-29)
  - 0.6.4 (2016-03-15)
  - 0.6.3 (2016-03-01)
  - 0.6.2 (2016-02-24)
  - 0.6.1 (2016-02-23)
  - 0.6.0 (2016-02-21)
  - 0.5.0 (2014-09-14)
  - 0.4.7 (2013-08-13)
  - 0.4.6 (2013-04-07)
  - 0.4.5 (2012-12-16)
  - 0.4.4 (2012-11-26)
  - 0.4.3 (2012-11-21)
  - 0.4.2 (2012-11-19)
  - 0.4.1 (2012-06-18)
  - 0.3 (2012-04-15)
  - 0.2 (2012-02-06)
  - 0.1 (2012-01-19)

# Plugin Developer’s Guide

- Writing Plugins
  - Hello World
  - Loading plugins
  - Command-line Options
  - Config File Options
  - Guidelines
  - Recipes
- Documenting plugins
- Event reference
  - `CommandLineArgsEvent`
  - `CreateTestsEvent`
  - `CreatedTestSuiteEvent`
  - `DescribeTestEvent`
  - `Event`
  - `GetTestCaseNamesEvent`
  - `HandleFileEvent`
  - `LoadFromModuleEvent`
  - `LoadFromNameEvent`
  - `LoadFromNamesEvent`
  - `LoadFromTestCaseEvent`
  - `MatchPathEvent`
  - `ModuleSuiteEvent`
  - `OutcomeDetailEvent`
  - `PluginsLoadedEvent`
  - `ReportSummaryEvent`
  - `ReportTestEvent`
  - `ResultCreatedEvent`
  - `ResultStopEvent`
  - `ResultSuccessEvent`
  - `RunnerCreatedEvent`
  - `StartLayerSetupEvent`
  - `StartLayerSetupTestEvent`
  - `StartLayerTeardownEvent`
  - `StartLayerTeardownTestEvent`
  - `StartTestEvent`
  - `StartTestRunEvent`
  - `StopLayerSetupEvent`
  - `StopLayerSetupTestEvent`
  - `StopLayerTeardownEvent`
  - `StopLayerTeardownTestEvent`
  - `StopTestEvent`
  - `StopTestRunEvent`
  - `TestOutcomeEvent`
  - `UserInteractionEvent`
- Hook reference
  - Pre-registration Hooks
  - Standard Hooks
  - User Interaction Hooks
- Session reference
  - Session
  - Config
- Plugin class reference
  - Plugin base class
  - Plugin interface classes

# Developer’s Guide

- Contributing to nose2
  - The Basics
  - Code Contributions
- Internals
  - nose2.main
  - nose2.exceptions
  - nose2.loader
  - nose2.result
  - nose2.runner
  - nose2.util

# Indices and tables

- Index

- Module Index

- Search Page