Add benchmarks/README.md and mention it in main README.md

Author: will-keen

README.md

@@ -25,6 +25,10 @@ $ make html
 
 The index page is at `docs/_build/html/index.html` - you can open this in a web browser.
 
+## Tests and benchmarks
+
+Please see `tests/README.md` and `benchmarks/README.md` for more information.
+
 ## Releases/versioning
 
 Releases are created using tags from the repository and can be found on [PyPI](https://pypi.org/project/constrainedrandom/).

benchmarks/README.md

@@ -0,0 +1,27 @@
+# Benchmarks
+
+These benchmarks are intended as developer-facing. They contain checks to ensure that performance has not degraded.
+
+## Extra requirements
+
+You need to install [`pyvsc`](https://pyvsc.readthedocs.io/en/latest/introduction.html) in order to run the benchmarks. This is not included in `pyproject.toml` as a dependency to avoid making installation size bigger than necessary.
+
+## Running
+
+To run, from the root of constrainedrandom:
+
+```
+python3 -m benchmarks
+```
+
+## Defining new benchmarks
+
+Benchmark test cases should inherit from `benchmarks.benchmark_utils.BenchmarkTestCase`.
+
+Each test case should implement a `get_randobjs()` method. This returns a dictionary of the random objects to be tested. Each should implement the `randomize()` function and be equivalent.
+
+Each test case should also implement a `check_perf()` method, so that the expected results are defined in an executable, checkable manner.
+
+## Shared framework
+
+The benchmarks use a shared testing framework with the unit tests. However, they are kept separate so that users don't have to install `pyvsc` to ensure basic functionality of constrainedrandom.