Metadata-Version: 2.1
Name: stestr
Version: 2.2.0
Summary: A parallel Python test runner built around subunit
Home-page: http://stestr.readthedocs.io/en/latest/
Author: Matthew Treinish
Author-email: mtreinish@kortar.org
License: UNKNOWN
Description: stestr
        ======
        
        .. image:: https://img.shields.io/travis/mtreinish/stestr/master.svg?style=flat-square
            :target: https://travis-ci.org/mtreinish/stestr
            :alt: Build status
        
        .. image:: https://img.shields.io/appveyor/ci/mtreinish/stestr/master.svg?logo=appveyor&style=flat-square
            :target: https://ci.appveyor.com/project/mtreinish/stestr
            :alt: Appveyor build status
        
        .. image:: https://img.shields.io/coveralls/github/mtreinish/stestr/master.svg?style=flat-square
            :target: https://coveralls.io/github/mtreinish/stestr?branch=master
            :alt: Code coverage
        
        .. image:: https://img.shields.io/pypi/v/stestr.svg?style=flat-square
            :target: https://pypi.python.org/pypi/stestr
            :alt: Latest Version
        
        You can see the full rendered docs at: http://stestr.readthedocs.io/en/latest/
        
        Overview
        --------
        
        stestr is parallel Python test runner designed to execute `unittest`_ test
        suites using multiple processes to split up execution of a test suite. It also
        will store a history of all test runs to help in debugging failures and
        optimizing the scheduler to improve speed. To accomplish this goal it uses the
        `subunit`_ protocol to facilitate streaming and storing results from multiple
        workers.
        
        .. _unittest: https://docs.python.org/3/library/unittest.html
        .. _subunit: https://github.com/testing-cabal/subunit
        
        stestr originally started as a fork of the `testrepository`_ that concentrates
        on being a dedicated test runner for python projects. The generic abstraction
        layers which enabled testrepository to work with any subunit emitting runner
        are gone. stestr hard codes python-subunit-isms into how it works. The code
        base is also designed to try and be explicit, and to provide a python api that
        is documented and has examples.
        
        .. _testrepository: https://testrepository.readthedocs.org/en/latest
        
        While stestr was originally forked from testrepository it is not 100% backwards
        compatible with testrepository. At a high level the basic concepts of operation
        are shared between the 2 projects but the actual usage between the 2 is not
        exactly the same.
        
        Installing stestr
        -----------------
        
        stestr is available via pypi, so all you need to do is run::
        
          pip install -U stestr
        
        to get stestr on your system. If you need to use a development version of
        stestr you can clone the repo and install it locally with::
        
          git clone https://github.com/mtreinish/stestr.git && pip install -e stestr
        
        which will install stestr in your python environment in editable mode for local
        development
        
        Using stestr
        ------------
        
        After you install stestr to use it to run tests is pretty straightforward. The
        first thing you'll need to do is create a ``.stestr.conf`` file for your
        project. This file is used to tell stestr where to find tests and basic
        information about how tests are run. A basic minimal example of the
        contents of this is::
        
          [DEFAULT]
          test_path=./project_source_dir/tests
        
        which just tells stestr the relative path for the directory to use for
        test discovery. This is the same as ``--start-directory`` in the standard
        `unittest discovery`_
        
        .. _unittest discovery: https://docs.python.org/3/library/unittest.html#test-discovery
        
        After this file is created you should be all set to start using stestr to run
        tests. You can create a repository for test results with the stestr init
        command, just run::
        
            stestr init
        
        and it will create a .stestr directory in your cwd that will be used to store
        test run results. (if you run stestr run it will create this if it doesn't
        exist) Then to run tests just use::
        
            stestr run
        
        it will then execute all the tests found by test discovery. If you're just
        running a single test (or module) and want to avoid the overhead of doing test
        discovery you can use the ``--no-discover``/``-n`` option.
        
        For all the details on these commands and more thorough explanation of options
        see the stestr manual: https://stestr.readthedocs.io/en/latest/MANUAL.html
        
        Migrating from testrepository
        -----------------------------
        
        If you have a project that is already using testrepository stestr's source repo
        contains a helper script for migrating your repo to use stestr. This script
        just creates a ``.stestr.conf`` file from a ``.testr.conf`` file.
        (assuming it uses a standard subunit.run test command format) To run
        this from your project repo just call::
        
            $STESTR_SOURCE_DIR/tools/testr_to_stestr.py
        
        and you'll have a ``.stestr.conf`` created.
        
        Building a manpage
        ------------------
        
        The stestr manual has been formatted so that it renders well as html and as a
        manpage. The html output and is autogenerated and published to:
        https://stestr.readthedocs.io/en/latest/MANUAL.html but the manpage has to be
        generated by hand. To do this you have to manually run sphinx-build with the
        manpage builder. This has been automated in a small script that should be run
        from the root of the stestr repository::
        
          tools/build_manpage.sh
        
        which will generate the troff file in doc/build/man/stestr.1 which is ready to
        be packaged and or put in your system's man pages.
        
        
Platform: UNKNOWN
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Provides-Extra: sql
Provides-Extra: test
