Notes on adding a test in CONTRIBUTING

Author: WardBrian

CONTRIBUTING.md

@@ -19,9 +19,45 @@ We heartily welcome pull requests. To ensure an effective contribution, please a
 1. For significant, invasive, or output-affecting changes, consider opening an issue for discussion before committing substantial time and effort.
 2. If you're new to the project, starting with the [Good first issues](https://github.com/ocaml-ppx/ocamlformat/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good-first-issue+%3Agreen_heart%3A%22) can be beneficial.
 3. Fork the repository and create your branch from `main`.
-4. If you've added code that should be tested, supplement it with tests located in the `test/` directory.
+4. If you've added code that should be tested, supplement it with tests located in the `test/` directory (see [Adding a test](#adding-a-test)).
 5. Ensure that the test suite passes (see [Running the tests](#running-the-tests) for instructions).
 
+### Adding a Test
+
+#### Unit Tests
+
+Unit tests are located in the `test/unit` directory and are written using [Alcotest](https://github.com/mirage/alcotest).
+
+#### cram-Style Tests
+
+The CLI tests are located in `test/cli` and are written using [cram testing](https://dune.readthedocs.io/en/latest/reference/cram.html).
+Each test is a `.t` file that contains shell commands and their expected outputs.
+To add a new test, create a new `.t` file, or add new commands (lines beginning with ` $`) to an existing file.
+
+#### Golden Tests
+
+The remainder of the tests are so called "golden" or "expect" tests. These tests all consist of running `ocamlformat` on
+`.ml` files and comparing the output to expected output stored in reference files. The `dune`
+configuration for this is automatically generated for you based on the files present in these directories.
+
+These are separated into `test/failing` and `test/passing` directories.
+
+To add a test showing currently incorrect behavior, add a `.ml` file to `test/failing/tests`.
+If command line arguments are needed, create a corresponding `.opts` file with the same base name.
+The output of these tests will be stored in `.broken-ref` files.
+
+To add a test showing correct behavior, add a `.ml` file to `test/passing/tests`.
+These are similar to the failing tests, including the use of the `.opts` files for command line arguments,
+however the same file will be tested against all of the built-in configurations (e.g. `default`, `janestreet`, etc.),
+with outputs appearing in sub folders named `refs.<configuration>`.
+
+In both cases, if multiple sets of options are desired, you can create
+multiple `.opts` files with names provided after a `-`, for example `mytest.ml` can
+have `mytest-foo.opts` and `mytest-bar.opts`. This will create multiple test targets.
+
+The first time you run the tests, the `dune.inc` file will be updated. Once you have promoted
+this, the tests will run (you may need to manually create blank files for the reference outputs at first).
+
 ### Running the Tests
 
 After building OCamlFormat, execute `dune runtest` to check for any regressions. There should be no unexpected diffs. If there are, promote all the diffs with `dune promote`.