docs: write guide on adding new test suites to circleci (#6773)

## Motivation
This PR aims to explain how to add new test suites in the contributing
docs. This can be highly useful for new contributors as a reference to
follow when writing new integrations for `dd-trace-py`.

## Checklist

- [X] Change(s) are motivated and described in the PR description.
- [X] Testing strategy is described if automated tests are not included
in the PR.
- [X] Risk is outlined (performance impact, potential for breakage,
maintainability, etc).
- [X] Change is maintainable (easy to change, telemetry, documentation).
- [X] [Library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
are followed. If no release note is required, add label
`changelog/no-changelog`.
- [X] Documentation is included (in-code, generated user docs, [public
corp docs](https://github.com/DataDog/documentation/)).
- [X] Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist

- [x] Title is accurate.
- [x] No unnecessary changes are introduced.
- [x] Description motivates each change.
- [x] Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes unless absolutely necessary.
- [x] Testing strategy adequately addresses listed risk(s).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] Release note makes sense to a user of the library.
- [x] Reviewer has explicitly acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment.
- [x] Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)
- [x] If this PR touches code that signs or publishes builds or
packages, or handles credentials of any kind, I've requested a review
from `@DataDog/security-design-and-guidance`.
- [x] This PR doesn't touch any of that.

---------

Co-authored-by: Emmett Butler <[email protected]>

Author: ericlaz

docs/contributing-integrations.rst

@@ -173,8 +173,9 @@ Many of the tests are based on "snapshots": saved copies of actual traces sent t
 `APM test agent <../README.md#use-the-apm-test-agent>`_.
 
 To update the snapshots expected by a test, first update the library and test code to generate
-new traces. Then, delete the snapshot file corresponding to your test. Use `docker-compose up -d testagent`
-to start the APM test agent, and re-run the test. Use `--pass-env` as described
+new traces. Then, delete the snapshot file corresponding to your test at ``tests/snapshots/<snapshot_file>``.
+
+Use `docker-compose up -d testagent` to start the APM test agent, and then re-run the test. Use `--pass-env` as described
 `here <../README.md#use-the-apm-test-agent>`_ to ensure that your test run can talk to the
 test agent. Once the run finishes, the snapshot file will have been regenerated.
 
@@ -248,6 +249,17 @@ are not yet any expected spans stored for it, so we need to create some.
     not match.
 13. Repeat steps 7 through 9 until you've achieved test coverage for the entire "happy path" of normal usage
     for the library you're integrating with, as well as coverage of any known likely edge cases.
+14. Enable the `snapshot` option in `.circleci/config.templ.yml` and run the test as a `machine_executor` at ``.circleci/config.templ.yml``
+    just like:
+
+.. code-block:: yaml
+
+  <test_suite_name>:
+    <<: *machine_executor
+    steps:
+      - run_test:
+          pattern: '<test_suite_name>'
+          snapshot: true
 
 
 Trace Examples

docs/contributing-testing.rst

@@ -117,3 +117,54 @@ when the riotfile changes. Thus, if you make changes to the riotfile, you need t
 
 You can commit and pull request the resulting changes to files in ``.riot/requirements`` alongside the
 changes you made to ``riotfile.py``.
+
+How do I add a new test suite?
+------------------------------
+
+We use `riot <https://ddriot.readthedocs.io/en/latest/>`_, a Python virtual environment constructor, to run the test suites.
+It is necessary to create a new ``Venv`` instance in ``riotfile.py`` if it does not exist already. It can look like this:
+
+.. code-block:: python
+
+    Venv(
+        name="asyncio",
+        command="pytest {cmdargs} tests/contrib/asyncio",
+        pys=select_pys(),
+        pkgs={
+            "pytest-asyncio": latest,
+        },
+        env={
+            "DD_ENV_VARIABLE": "1",  # if needed
+        },
+    )
+
+Once a ``Venv`` instance has been created, you will be able to run it as explained in the section below.
+Next, we will need to add a new CircleCI job to run the newly added test suite at ``.circleci/config.templ.yml`` just like:
+
+.. code-block:: python
+
+    asyncio:
+    <<: *contrib_job
+    steps:
+      - run_test:
+          pattern: 'asyncio'
+
+
+After this, a new component must be added to ``tests/.suitespec.json`` under ``"components":`` like:
+
+.. code-block:: JSON
+
+    "asyncio": [
+        "ddtrace/contrib/asyncio/*"
+    ],
+
+Lastly, we will register it as a suite in the same file under ``"suites":``:
+
+.. code-block:: JSON
+
+    "asyncio": [
+        "@asyncio",
+        "tests/contrib/asyncio/*"
+    ],
+
+Once you've completed these steps, CircleCI will run the new test suite.