From 4997d1c83870c00ec7934ce55570e1d3fbade66f Mon Sep 17 00:00:00 2001
From: Mike Frysinger <vapier@google.com>
Date: Sun, 1 Dec 2019 22:47:21 -0500
Subject: [PATCH] tox: add & document tox usage

This makes it easy to run all the tests against multiple versions
of Python.  We want to make sure Python 2.7 & 3.6+ work.

Change-Id: Ia7b16eb46a2aa7c240f03bb291987fa8cb215267
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/247174
Reviewed-by: David Pursehouse <dpursehouse@collab.net>
Tested-by: Mike Frysinger <vapier@google.com>
---
 .gitignore            |  2 ++
 SUBMITTING_PATCHES.md | 34 +++++++++++++++++++++++++++++++---
 tox.ini               | 22 ++++++++++++++++++++++
 3 files changed, 55 insertions(+), 3 deletions(-)
 create mode 100644 tox.ini

diff --git a/.gitignore b/.gitignore
index f6b74f3d..d4b230a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,8 @@
 *.egg-info/
+*.log
 *.pyc
 __pycache__
 /dist
 .repopickle_*
 /repoc
+/.tox
diff --git a/SUBMITTING_PATCHES.md b/SUBMITTING_PATCHES.md
index e8a72e87..5021e7ee 100644
--- a/SUBMITTING_PATCHES.md
+++ b/SUBMITTING_PATCHES.md
@@ -69,10 +69,38 @@ suppressed in the included `.flake8` file.
 
 ## Running tests
 
-There is a [`./run_tests`](./run_tests) helper script for quickly invoking all
-of our unittests.  The coverage isn't great currently, but it should still be
-run for all commits.
+We use [pytest](https://pytest.org/) and [tox](https://tox.readthedocs.io/) for
+running tests.  You should make sure to install those first.
 
+To run the full suite against all supported Python versions, simply execute:
+```sh
+$ tox -p auto
+```
+
+We have [`./run_tests`](./run_tests) which is a simple wrapper around `pytest`:
+```sh
+# Run the full suite against the default Python version.
+$ ./run_tests
+# List each test as it runs.
+$ ./run_tests -v
+
+# Run a specific unittest module (and all tests in it).
+$ ./run_tests tests/test_git_command.py
+
+# Run a specific testsuite in a specific unittest module.
+$ ./run_tests tests/test_editor.py::EditString
+
+# Run a single test.
+$ ./run_tests tests/test_editor.py::EditString::test_cat_editor
+
+# List all available tests.
+$ ./run_tests --collect-only
+
+# Run a single test using substring match.
+$ ./run_tests -k test_cat_editor
+```
+
+The coverage isn't great currently, but it should still be run for all commits.
 Adding more unittests for changes you make would be greatly appreciated :).
 Check out the [tests/](./tests/) subdirectory for more details.
 
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 00000000..02c5647d
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,22 @@
+# Copyright 2019 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# https://tox.readthedocs.io/
+
+[tox]
+envlist = py27, py36, py37, py38
+
+[testenv]
+deps = pytest
+commands = {toxinidir}/run_tests