Add libparsec_testbed crate docs

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

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.

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)]