# Module `case`

Enhance `unittest.TestCase`:

- a new loop is issued and set as the default loop before each test, and closed and disposed after,
- if the loop uses a selector, it will be wrapped with `asynctest.TestSelector`,
- a test method in a TestCase identified as a coroutine function or returning a coroutine will run on the loop,
- `setUp()` and `tearDown()` methods can be coroutine functions,
- cleanup functions registered with `addCleanup()` can be coroutine functions,
- a test fails if the loop did not run during the test.

## class-level set-up

Since each test runs in its own loop, it is not possible to run `setUpClass()` and `tearDownClass()` as coroutines.

If one needs to perform set-up actions at the class level (meaning once for all tests in the class), it should be done using a loop created for this sole purpose and that is not shared with the tests. Ideally, the loop shall be closed in the method which creates it.

If one really needs to share a loop between tests, `TestCase.use_default_loop` can be set to `True` (as a class attribute). The test case will use the loop returned by `asyncio.get_event_loop()` instead of creating a new loop for each test. This way, the event loop or event loop policy can be set during class-level set-up and tear down.

## TestCases

class `asynctest.``TestCase`(methodName='runTest')

  A test which is a coroutine function or which returns a coroutine will run on the loop.

  Once the test returned, one or more assertions are checked. For instance, a test fails if the loop didn’t run. These checks can be enabled or disabled using the `fail_on()` decorator.

  By default, a new loop is created and is set as the default loop before each test. Test authors can retrieve this loop with `loop`.

  If `use_default_loop` is set to `True`, the current default event loop is used instead. In this case, it is up to the test author to deal with the state of the loop in each test: the loop might be closed, callbacks and tasks may be scheduled by previous tests. It is also up to the test author to close the loop and dispose the related resources.

  If `forbid_get_event_loop` is set to `True`, a call to `asyncio.get_event_loop()` will raise an `AssertionError`. Since Python 3.6, calling `asyncio.get_event_loop()` from a callback or a coroutine will return the running loop (instead of raising an exception).

  These behaviors should be configured when defining the test case class:

      class With_Reusable_Loop_TestCase(asynctest.TestCase):
          use_default_loop = True

          forbid_get_event_loop = False

          def test_something(self):
              pass

  If `setUp()` and `tearDown()` are coroutine functions, they will run on the loop. Note that `setUpClass()` and `tearDownClass()` can not be coroutines.

  New in version 0.5: attribute `use_default_loop`.

  New in version 0.7: attribute `forbid_get_event_loop`. In any case, the default loop is now reset to its original state outside a test function.

  New in version 0.8: `ignore_loop` has been deprecated in favor of the extensible `fail_on()` decorator.

  `setUp`()

    Method or coroutine called to prepare the test fixture.

    see `unittest.TestCase.setUp()`

  `tearDown`()

    Method called immediately after the test method has been called and the result recorded.

    see `unittest.TestCase.tearDown()`

  `addCleanup`(function, *args, **kwargs)

    Add a function, with arguments, to be called when the test is completed. If function is a coroutine function, it will run on the loop before it’s cleaned.

  `assertAsyncRaises`(exception, awaitable)

    Test that an exception of type `exception` is raised when an exception is raised when awaiting `awaitable`, a future or coroutine.

    See: | `unittest.TestCase.assertRaises()`

  `assertAsyncRaisesRegex`(exception, regex, awaitable)

    Like `assertAsyncRaises()` but also tests that `regex` matches on the string representation of the raised exception.

    See: | `unittest.TestCase.assertRaisesRegex()`

  `assertAsyncWarns`(warning, awaitable)

    Test that a warning is triggered when awaiting `awaitable`, a future or a coroutine.

    See: | `unittest.TestCase.assertWarns()`

  `assertAsyncWarnsRegex`(warning, regex, awaitable)

    Like `assertAsyncWarns()` but also tests that `regex` matches on the message of the triggered warning.

    See: | `unittest.TestCase.assertWarnsRegex()`

  `doCleanups`()

    Execute all cleanup functions. Normally called for you after tearDown.

  `forbid_get_event_loop` = False

    If true, the value returned by `asyncio.get_event_loop()` will be set to `None` during the test. It allows to ensure that tested code use a loop object explicitly passed around.

  `loop` = None

    Event loop created and set as default event loop during the test.

  `use_default_loop` = False

    If true, the loop used by the test case is the current default event loop returned by `asyncio.get_event_loop()`. The loop will not be closed and recreated between tests.

class `asynctest.``FunctionTestCase`(testFunc, setUp=None, tearDown=None, description=None)

  Enables the same features as `TestCase`, but for `FunctionTestCase`.

class `asynctest.``ClockedTestCase`(methodName='runTest')

  Subclass of `TestCase` with a controlled loop clock, useful for testing timer based behaviour without slowing test run time.

  The clock will only advance when `advance()` is called.

  `advance`(seconds)

    Fast forward time by a number of `seconds`.

    Callbacks scheduled to run up to the destination clock time will be executed on time:

        >>> self.loop.call_later(1, print_time)
        >>> self.loop.call_later(2, self.loop.call_later, 1, print_time)
        >>> await self.advance(3)
        1
        3

    In this example, the third callback is scheduled at `t = 2` to be executed at `t + 1`. Hence, it will run at `t = 3`. The callback as been called on time.

## Decorators

`@``asynctest.``fail_on`(**checks)

  Enable checks on the loop state after a test ran to help testers to identify common mistakes.

  Enable or disable a check using a keywork argument with a boolean value:

      @asynctest.fail_on(unused_loop=True)
      class TestCase(asynctest.TestCase):
          ...

  Available checks are:

  > - `unused_loop`: disabled by default, checks that the loop ran at least once during the test. This check can not fail if the test method is a coroutine. This allows to detect cases where a test author assume its test will run tasks or callbacks on the loop, but it actually didn’t.
  > - `active_selector_callbacks`: enabled by default, checks that any registered reader or writer callback on a selector loop (with `add_reader()` or `add_writer()`) is later explicitly unregistered (with `remove_reader()` or `remove_writer()`) before the end of the test.
  > - `active_handles`: disabled by default, checks that there is not scheduled callback left to be executed on the loop at the end of the test. The helper `exhaust_callbacks()` can help to give a chance to the loop to run pending callbacks.

  The decorator of a method has a greater priority than the decorator of a class. When `fail_on()` decorates a class and one of its methods with conflicting arguments, those of the class are overriden.

  Subclasses of a decorated `TestCase` inherit of the checks enabled on the parent class.

  New in version 0.8.

  New in version 0.9: `active_handles`

  New in version 0.12: `unused_loop` is now deactivated by default to maintain compatibility with non-async test inherited from `unittest.TestCase`. This check is especially useful to track missing `@asyncio.coroutine` decorators in a codebase that must be compatbible with Python 3.4.

`@``asynctest.``strict`

  Activate strict checking of the state of the loop after a test ran.

  It is a shortcut to `fail_on()` with all checks set to `True`.

  Note that by definition, the behavior of `strict()` will change in the future when new checks will be added, and may break existing tests with new errors after an update of the library.

  New in version 0.8.

`@``asynctest.``lenient`

  Deactivate all checks performed after a test ran.

  It is a shortcut to `fail_on()` with all checks set to `False`.

  New in version 0.8.

`@``asynctest.``ignore_loop`

  By default, a test fails if the loop did not run during the test (including set up and tear down), unless the `TestCase` class or test function is decorated by `ignore_loop()`.

  > Deprecated since version 0.8: Use `fail_on()` with `unused_loop=False` instead.