From 05bff2bd41a7d1930dbfc4eb87a19e1461f5b467 Mon Sep 17 00:00:00 2001 From: Jason Pellerin Date: Tue, 19 Dec 2006 03:35:52 +0000 Subject: [0.10-dev] Imported last revision from python-hosting to start 0.10-dev branch --- README.txt | 287 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 README.txt (limited to 'README.txt') diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..d1158ea --- /dev/null +++ b/README.txt @@ -0,0 +1,287 @@ +nose: a discovery-based unittest extension. + +nose provides an alternate test discovery and running process for +unittest, one that is intended to mimic the behavior of py.test as much +as is reasonably possible without resorting to too much magic. + +Basic usage +----------- + +Use the nosetests script (after installation by setuptools):: + + nosetests [options] [(optional) test files or directories] + +You may also use nose in a test script:: + + import nose + nose.main() + +If you don't want the test script to exit with 0 on success and 1 on failure +(like unittest.main), use nose.run() instead:: + + import nose + result = nose.run() + +`result` will be true if the test run succeeded, or false if any test failed +or raised an uncaught exception. Lastly, you can run nose.core directly, which +will run nose.main():: + + python /path/to/nose/core.py + +Please see the usage message for the nosetests script for information +about how to control which tests nose runs, which plugins are loaded, +and the test output. + +Features +-------- + +Run as collect +============== + +nose begins running tests as soon as the first test module is loaded, it +does not wait to collect all tests before running the first. + +Output capture +============== + +Unless called with the -s (--nocapture) switch, nose will capture stdout +during each test run, and print the captured output only for tests that +fail or have errors. The captured output is printed immediately +following the error or failure output for the test. (Note that output in +teardown methods is captured, but can't be output with failing tests, +because teardown has not yet run at the time of the failure.) + +Assert introspection +==================== + +When run with the -d (--detailed-errors) switch, nose will try to output +additional information about the assert expression that failed with each +failing test. Currently, this means that names in the assert expression +will be expanded into any values found for them in the locals or globals +in the frame in which the expression executed. + +In other words if you have a test like:: + + def test_integers(): + a = 2 + assert a == 4, "assert 2 is 4" + +You will get output like:: + + File "/path/to/file.py", line XX, in test_integers: + assert a == 4, "assert 2 is 4" + AssertionError: assert 2 is 4 + >> assert 2 == 4, "assert 2 is 4" + +Setuptools integration +====================== + +nose may be used with the setuptools_ test command. Simply specify +nose.collector as the test suite in your setup file:: + + setup ( + # ... + test_suite = 'nose.collector' + ) + +Then to find and run tests, you can run:: + + python setup.py test + +When running under setuptools, you can configure nose settings via the +environment variables detailed in the nosetests script usage message. + +Please note that when run under the setuptools test command, some plugins will +not be available, including the builtin coverage, profiler, and missed test +plugins. + +nose also includes its own setuptools command, `nosetests`, that provides +support for all plugins and command line options, as well as configuration +using the setup.cfg file. See nose.commands_ for more information about the +`nosetests` command. + +.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools +.. _nose.commands: #commands + +Writing tests +------------- + +As with py.test, nose tests need not be subclasses of TestCase. Any function +or class that matches the configured testMatch regular expression +('(?:^|[\b_\.-])[Tt]est)'' by default) and lives in a module that also +matches that expression will be run as a test. For the sake of compatibility +with legacy unittest test cases, nose will also load tests from +unittest.TestCase subclasses just like unittest does. Like py.test, functional +tests will be run in the order in which they appear in the module +file. TestCase derived tests and other test classes are run in alphabetical +order. + +Fixtures +======== + +nose supports fixtures (setup and teardown methods) at the package, +module, and test level. As with py.test or unittest fixtures, setup always +runs before any test (or collection of tests for test packages and modules); +teardown runs if setup has completed successfully, whether or not the test +or tests pass. For more detail on fixtures at each level, see below. + +Test packages +============= + +nose allows tests to be grouped into test packages. This allows +package-level setup; for instance, if you need to create a test database +or other data fixture for your tests, you may create it in package setup +and remove it in package teardown once per test run, rather than having to +create and tear it down once per test module or test case. + +To create package-level setup and teardown methods, define setup and/or +teardown functions in the __init__.py of a test package. Setup methods may +be named 'setup', 'setup_package', 'setUp',or 'setUpPackage'; teardown may +be named 'teardown', 'teardown_package', 'tearDown' or 'tearDownPackage'. +Execution of tests in a test package begins as soon as the first test +module is loaded from the test package. + +Test modules +============ + +A test module is a python module that matches the testMatch regular +expression. Test modules offer module-level setup and teardown; define the +method 'setup', 'setup_module', 'setUp' or 'setUpModule' for setup, +'teardown', 'teardown_module', or 'tearDownModule' for teardown. Execution +of tests in a test module begins after all tests are collected. + +Test classes +============ + +A test class is a class defined in a test module that is either a subclass +of unittest.TestCase, or matches testMatch. Test classes that don't +descend from unittest.TestCase are run in the same way as those that do: +methods in the class that match testMatch are discovered, and a test case +constructed to run each with a fresh instance of the test class. Like +unittest.TestCase subclasses, other test classes may define setUp and +tearDown methods that will be run before and after each test method. + +Test functions +============== + +Any function in a test module that matches testMatch will be wrapped in a +FunctionTestCase and run as a test. The simplest possible failing test is +therefore:: + + def test(): + assert False + +And the simplest passing test:: + + def test(): + pass + +Test functions may define setup and/or teardown attributes, which will be +run before and after the test function, respectively. A convenient way to +do this, especially when several test functions in the same module need +the same setup, is to use the provided with_setup decorator:: + + def setup_func(): + # ... + + def teardown_func(): + # ... + + @with_setup(setup_func,teardown_func) + def test(): + # ... + +For python 2.3, add the attributes by calling the decorator function like +so:: + + def test(): + # ... + test = with_setup(setup_func,teardown_func)(test) + +or by direct assignment:: + + test.setup = setup_func + test.teardown = teardown_func + +Test generators +=============== + +nose supports test functions and methods that are generators. A simple +example from nose's selftest suite is probably the best explanation:: + + def test_evens(): + for i in range(0, 5): + yield check_even, i, i*3 + + def check_even(n, nn): + assert n % 2 == 0 or nn % 2 == 0 + +This will result in 4 tests. nose will iterate the generator, creating a +function test case wrapper for each tuple it yields. As in the example, test +generators must yield tuples, the first element of which must be a callable +and the remaining elements the arguments to be passed to the callable. + +Setup and teardown functions may be used with test generators. The setup and +teardown attributes must be attached to the generator function:: + + @with_setup(setup_func, teardown_func) + def test_generator(): + ... + yield func, arg, arg ... + +The setup and teardown functions will be executed for each test that the +generator returns. + +For generator methods, the setUp and tearDown methods of the class (if any) +will be run before and after each generated test case. + +Please note that method generators `are not` supported in unittest.TestCase +subclasses. + +About the name +-------------- + +* nose is the least silly short synonym for discover in the dictionary.com + thesaurus that does not contain the word 'spy'. +* Pythons have noses +* The nose knows where to find your tests +* Nose Obviates Suite Employment + +Contact the author +------------------ + +To report bugs, ask questions, or request features, please use the trac +instance provided by the great folks at python hosting, here: +http://nose.python-hosting.com. Or, email the author at +jpellerin+nose at gmail dot com. Patches are welcome! + +Similar test runners +-------------------- + +nose was inspired mainly by py.test_, which is a great test runner, but +formerly was not all that easy to install, and is not based on unittest. + +Test suites written for use with nose should work equally well with py.test, +and vice versa, except for the differences in output capture and command line +arguments for the respective tools. + +.. _py.test: http://codespeak.net/py/current/doc/test.html + +License and copyright +--------------------- + +nose is copyright Jason Pellerin 2005-2006 + +This program is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public +License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with this program; if not, write to the Free Software Foundation, +Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -- cgit v1.2.1