From b32fa56d53ac917da06d55dd8c2057b9f6d5000b Mon Sep 17 00:00:00 2001
From: Marcos Medrano <marcosmedrano0@gmail.com>
Date: Wed, 8 Jan 2025 12:08:31 +0100
Subject: [PATCH] Add libparsec_testbed crate docs

---
 libparsec/README.md                 |  2 +-
 libparsec/crates/testbed/README.md  | 70 +++++++++++++++++++++++++++++
 libparsec/crates/testbed/src/lib.rs |  2 +-
 3 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 libparsec/crates/testbed/README.md

diff --git a/libparsec/README.md b/libparsec/README.md
index e06aa7c305c..46bc3c0592e 100644
--- a/libparsec/README.md
+++ b/libparsec/README.md
@@ -85,7 +85,7 @@ Here, "testing" refers to two use-cases:
 2. Running the application with test feature (e.g. we want to run the GUI with an
    dummy organization already configured for quick testing purpose)
 
-- `testbed`:
+- `testbed`: Defines common organization templates to prevent code duplication in tests.
 - `tests_macros`: Defines the `#[parsec_test]` macro that is used to decorate each
   test function. Among other things, this macro conveniently handles setting up
   Tokio context (so that our test can be an asynchronous function) and the testbed
diff --git a/libparsec/crates/testbed/README.md b/libparsec/crates/testbed/README.md
new file mode 100644
index 00000000000..7019580f1fc
--- /dev/null
+++ b/libparsec/crates/testbed/README.md
@@ -0,0 +1,70 @@
+# Libparsec Testbed
+
+The `libparsec_testbed` crate defines common organization templates to prevent code
+duplication in tests.
+
+## Organization templates
+
+A template defines the structure of an organization such as:
+
+- the users & their devices
+- the workspaces & their sharing rules
+- the files and directories inside each workspace
+
+Within a test, this is usually a good starting point (hence the name) and the
+organization can be further customized in a way that is relevant to the test
+(e.g. revoke an existing user).
+
+Templates also allow to create deterministic tests based on the events that
+should be triggered, the order in which they should be triggered or the
+specific timestamp at which they should be triggered.
+
+## Use in tests
+
+The templates defined in this crate are used to test Libparsec, Parsec CLI and
+the Parsec Server.
+
+### Libparsec testing
+
+The templates can be enabled via the `#[parsec_test]` macro defined in the
+`tests_macros` crate.
+
+```rust
+#[parsec_test(testbed = "coolorg")]
+async fn my_test_function(
+    // ...
+    env: &TestbedEnv,
+){
+  // access and customize the organization via the TestbedEnv
+}
+```
+
+### Parsec CLI testing
+
+Currently, the testbed is only partially used in Parsec CLI tests to provide a
+basic Parsec Server and setup/create organization from there (so templates are
+not used). See https://github.com/Scille/parsec-cloud/issues/9144.
+
+### Parsec Server testing
+
+The templates are exposed as pytest fixtures in `server/tests/common/client.py`.
+
+## Internals
+
+Organization templates are created with a `TestbedTemplateBuilder` and exposed
+via the `TESTBED_TEMPLATES` array.
+
+Example:
+
+```rust
+let mut builder = TestbedTemplate::from_builder("my_organization");
+builder.bootstrap_organization("alice"); // alice@dev1
+builder
+    .new_user("bob")
+    .with_initial_profile(UserProfile::Standard); // bob@dev1
+builder.new_device("alice"); // alice@dev2
+builder.new_device("bob"); // bob@dev2
+```
+
+The easiest way to add a new template is to take a look at the existing ones in
+the the `templates/` directory.
diff --git a/libparsec/crates/testbed/src/lib.rs b/libparsec/crates/testbed/src/lib.rs
index 0f4f9608e7c..5a816bba991 100644
--- a/libparsec/crates/testbed/src/lib.rs
+++ b/libparsec/crates/testbed/src/lib.rs
@@ -1,5 +1,5 @@
 // Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
-
+#![doc = include_str!("../README.md")]
 // This lib provide helpers that are used for testing purpose.
 // To simplify the writing of those helpers, we use the same rule for when writing tests.
 #![allow(clippy::unwrap_used)]