From bfd13d5d265eff15f4109d2d15c4859122241986 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Wed, 20 Nov 2024 17:21:03 +0100 Subject: [PATCH] docs(test): Add a contribution guide for tests --- CONTRIBUTING.md | 2 ++ test/README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 test/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97f53be1..6531f07c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,8 @@ If you have a specific change you'd like to submit, be it documentation, bug fix > > The simplest way of contacting us is by creating an issue on this repository, or commenting in an existing issue. Some projects may also have a Discord server, if you prefer reaching us there. +A simple way to contribute is to [submit integration tests](test/README.md) for features that are important to you, to ensure we won't accidentally break them. + ## Issue tracking If you want to contribute, but do not know what to improve, we recommend going through to existing issues. diff --git a/test/README.md b/test/README.md new file mode 100644 index 00000000..45e1c5a4 --- /dev/null +++ b/test/README.md @@ -0,0 +1,52 @@ +# Integration tests + +This folder contains integration tests using the driver. They are run in CI against the last 3 stable versions of MongoDB, so we can ensure new versions don't break anything. + +We highly welcome contributions adding simple scenarii or complex requests that are important to you. This way, we will ensure they continue to work and use them as the basis for future performance or syntax improvements. + +This could be as simple as a request using some strange combination of options, or as complex as massive aggregations that impact each other. + +If you'd like to contribute, but don't know how to, please read our [contribution guide](https://opensavvy.dev/open-source/index.html#contributing-to-open-source-projects). The rest of this document describes how to edit this project but doesn't explain our general workflow regarding contributions. + +## Requirements + +Before starting, use this command to check if you have a valid Docker installation: +```shell +docker run -it hello-world +``` + +You will also need a valid Java installation, use this command to check if you have one: +```shell +java -version +``` + +The tests require a running MongoDB instance. To start one, click here: `MongoDB`. If you're not using IntelliJ, open [docker-compose.yml](../docker/docker-compose.yml) and run the MongoDB service (from the root of the repository): +```shell +cd docker +docker compose up -d +``` + +Finally, run the existing tests before editing anything, to ensure they all pass: `Check`. If you're not using IntelliJ, run (from the root of the repository): +```shell +./gradlew check +``` + +## Add your scenario + +Open the folder [src/commonTest/kotlin](src/commonTest/kotlin) and create a new Kotlin file. Take inspiration from other existing tests, in particular [BasicReadWriteTest](src/commonTest/kotlin/BasicReadWriteTest.kt). + +These tests use the [Prepared test framework](https://opensavvy.gitlab.io/groundwork/prepared/docs/). The most important things to know are: +- Tests are declared in a class that implements `PreparedSpec`. +- `by testCollection("collection-name")` is used to dynamically generate a new collection on each execution (to ensure parallel tests don't impact each other). The name of the collection is printed in the standard output of the test so you can go observe it afterward. +- The `check` function is used to make assertions. Assertions should not be split into multiple lines nor intermediary variables. +- Most functions should have a quick documentation (CTRL Q by default in IntelliJ). + +Once you're done writing your test, execute it with `Check`. If you're not using IntelliJ, run (from the root of the repository): +```shell +./gradlew check +``` + +Each test should automatically print details on which collections it modified. If a test fails, the collections are kept so you can observe them yourself. In IntelliJ, you can open the "Database" tool window which should already be configured to read from the database. Otherwise, you can connect with any other tool using the URL: +```text +mongodb://localhost:27017 +``` -- 2.51.2