fix tox to test examples again
add detox tox env for faster testing
clean up makefile, add tox target
add extra group for installing dev requirements
clean up contributing doc, build with docs
expand issue template
add pull request template
The minimal requirement for running the testsuite is ``pytest``. You can
install it with::
pytest
pip install pytest
This only runs the tests for the current environment. Whether this is relevant
depends on which part of Flask you're working on. Travis-CI will run the full
suite when you submit your pull request.
Clone this repository::
The full test suite takes a long time to run because it tests multiple
combinations of Python and dependencies. You need to have Python 2.6, 2.7, 3.3,
3.4, 3.5 3.6, and PyPy 2.7 installed to run all of the environments. Then run::
git clone https://github.com/pallets/flask.git
Install Flask as an editable package using the current source::
cd flask
pip install --editable .
Running the testsuite
---------------------
The minimal requirement for running the testsuite is ``pytest``. You can
install it with::
pip install pytest
Then you can run the testsuite with::
pytest tests/
**Shortcut**: ``make test`` will ensure ``pytest`` is installed, and run it.
With only pytest installed, a large part of the testsuite will get skipped
though. Whether this is relevant depends on which part of Flask you're working
on. Travis is set up to run the full testsuite when you submit your pull
request anyways.
If you really want to test everything, you will have to install ``tox`` instead
of ``pytest``. You can install it with::
pip install tox
The ``tox`` command will then run all tests against multiple combinations
Python versions and dependency versions.
**Shortcut**: ``make tox-test`` will ensure ``tox`` is installed, and run it.
tox
Running test coverage
---------------------
Generating a report of lines that do not have unit test coverage can indicate where
to start contributing. ``pytest`` integrates with ``coverage.py``, using the ``pytest-cov``
plugin. This assumes you have already run the testsuite (see previous section)::
~~~~~~~~~~~~~~~~~~~~~
pip install pytest-cov
Generating a report of lines that do not have test coverage can indicate
where to start contributing. Run ``pytest`` using ``coverage`` and generate a
report on the terminal and as an interactive HTML document::
After this has been installed, you can output a report to the command line using this command::
coverage run -m pytest
coverage report
coverage html
# then open htmlcov/index.html
pytest --cov=flask tests/
Read more about `coverage <https://coverage.readthedocs.io>`_.
Generate a HTML report can be done using this command::
Running the full test suite with ``tox`` will combine the coverage reports
from all runs.
pytest --cov-report html --cov=flask tests/
``make`` targets
~~~~~~~~~~~~~~~~
Full docs on ``coverage.py`` are here: https://coverage.readthedocs.io
Flask provides a ``Makefile`` with various shortcuts. They will ensure that
all dependencies are installed.
**Shortcut**: ``make cov`` will ensure ``pytest-cov`` is installed, run it, display the results, *and* save the HTML report.
- ``make test`` runs the basic test suite with ``pytest``
- ``make cov`` runs the basic test suite with ``coverage``
- ``make test-all`` runs the full test suite with ``tox``
- ``make docs`` builds the HTML documentation
Caution: zero-padded file modes
-------------------------------
Caution
=======
pushing
-------
This repository contains several zero-padded file modes that may cause issues when pushing this repository to git hosts other than github. Fixing this is destructive to the commit history, so we suggest ignoring these warnings. If it fails to push and you're using a self-hosted git service like Gitlab, you can turn off repository checks in the admin panel.
This repository contains several zero-padded file modes that may cause issues
when pushing this repository to git hosts other than GitHub. Fixing this is
destructive to the commit history, so we suggest ignoring these warnings. If it
fails to push and you're using a self-hosted git service like GitLab, you can
turn off repository checks in the admin panel.
cloning
-------
The zero-padded file modes files above can cause issues while cloning, too. If you have
::
These files can also cause issues while cloning. If you have ::
[fetch]
fsckobjects = true
or
::
or ::
[receive]
fsckObjects = true
set in your git configuration file, cloning this repository will fail. The only solution is to set both of the above settings to false while cloning, and then setting them back to true after the cloning is finished.
set in your git configuration file, cloning this repository will fail. The only
solution is to set both of the above settings to false while cloning, and then
setting them back to true after the cloning is finished.
David Lord
8 years ago