Merge pull request #2653 from input-output-hk/djo/2580/test-structure-adr+remove-test_tools_flag

chore: add dev adr for guidelines on writting test utilities + remove `test_tools` and `full` features from `mithril-common`

Author: jpraynaud

Cargo.lock

@@ -23,6 +23,48 @@ To complete
 To complete
 -->
 
+### 4. Guidelines for crate test utilities
+
+**Date:** 2025-07-25
+**Status:** Accepted
+
+### Context
+
+- Testing requires reusable utilities that may need to be shared across crates
+- Test utilities should be isolated from production code while remaining accessible to child crates
+- We need to minimize feature flags to optimize Rust compiler artifact reuse and reduce build times
+
+### Decision
+
+Test utilities must follow this organizational structure:
+
+**Core Rules:**
+
+1. All test utilities belong in a dedicated `test` module within each crate
+2. Utilities become public only when used by child crates or integration tests
+3. Public test utilities must not introduce additional dependencies
+4. Private test utilities are gated behind `cfg(test)`
+5. Import paths must explicitly include `test` modules to prevent accidental production usage
+6. Feature flags are prohibited for test utility isolation
+
+**Module Organization:**
+
+- **Test doubles** (mocks, fakes, stubs): `test::double` module
+- **Test data builders**: `test::builder` module
+- **Test-only type extensions**: Extension traits in `test` module
+  - Trait names end with `TestExtension`
+  - Implementations follow trait definitions, except when accessing private fields
+
+#### Consequences
+
+- Consistent codebase organization across all crates
+- Clear separation between production and test code
+- Improved discoverability and maintainability of test utilities
+- Reduced build times through minimal feature flag usage
+- Enhanced reusability of test utilities across child crates
+
+---
+
 ### 3. Guidelines for Dummy Test Doubles
 
 **Date:** 2025-07-22
@@ -51,7 +93,7 @@ The following guidelines will be adopted for implementing the `Dummy` trait:
 
 ---
 
-## 2. Remove Artifacts serialization support when compiling to WebAssembly
+## 2. Remove artifacts serialization support when compiling to WebAssembly
 
 date: 2025-02-26
 status: Accepted
@@ -88,7 +130,7 @@ In the future, if we need to serialize and deserialize Artifacts in WebAssembly,
 
 ---
 
-## 1. Record Architecture Decisions
+## 1. Record architecture decisions
 
 date: 2025-02-26
 status: Accepted

DEV-ADR.md

@@ -100,7 +100,7 @@
             // args);
 
         mithril-stm = buildPackage ./mithril-stm/Cargo.toml null {};
-        mithril-common = buildPackage ./mithril-common/Cargo.toml mithril-stm.cargoArtifacts { cargoExtraArgs = "-p mithril-common --features full"; };
+        mithril-common = buildPackage ./mithril-common/Cargo.toml mithril-stm.cargoArtifacts { cargoExtraArgs = "-p mithril-common"; };
         mithril = buildPackage null mithril-common.cargoArtifacts {
           doCheck = false;
         };

flake.nix

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-cardano-node-chain"
-version = "0.1.6"
+version = "0.1.7"
 authors.workspace = true
 documentation.workspace = true
 edition.workspace = true
@@ -35,7 +35,6 @@ kes-summed-ed25519 = { version = "0.2.1", features = [
     "serde_enabled",
     "sk_clone_enabled",
 ] }
-mithril-common = { path = "../../../mithril-common", features = ["test_tools"] }
 mockall = { workspace = true }
 pallas-crypto = "0.33.0"
 slog-async = { workspace = true }

internal/cardano-node/mithril-cardano-node-chain/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-cardano-node-internal-database"
-version = "0.1.4"
+version = "0.1.5"
 description = "Mechanisms that allow Mithril nodes to read the files of a Cardano node internal database and compute digests from them"
 authors.workspace = true
 documentation.workspace = true
@@ -29,7 +29,6 @@ walkdir = "2.5.0"
 
 [dev-dependencies]
 criterion = { version = "0.6.0", features = ["html_reports", "async_tokio"] }
-mithril-common = { path = "../../../mithril-common", version = ">=0.5", features = ["test_tools"] }
 mockall = { workspace = true }
 slog-async = { workspace = true }
 slog-term = { workspace = true }

internal/cardano-node/mithril-cardano-node-internal-database/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-aggregator-client"
-version = "0.1.0"
+version = "0.1.1"
 description = "Client to request data from a Mithril Aggregator"
 authors.workspace = true
 documentation.workspace = true
@@ -28,7 +28,6 @@ tokio = { workspace = true }
 [dev-dependencies]
 http = "1.3.1"
 httpmock = "0.7.0"
-mithril-common = { path = "../../mithril-common", version = ">=0.5", features = ["test_tools"] }
 mockall = { workspace = true }
 slog-async = { workspace = true }
 slog-term = { workspace = true }

internal/mithril-aggregator-client/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "mithril-dmq"
 description = "Mechanisms to publish and consume messages of a 'Decentralized Message Queue network' through a DMQ node"
-version = "0.1.7"
+version = "0.1.8"
 authors.workspace = true
 documentation.workspace = true
 edition.workspace = true
@@ -24,7 +24,6 @@ slog = { workspace = true }
 tokio = { workspace = true, features = ["sync"] }
 
 [dev-dependencies]
-mithril-common = { path = "../../mithril-common", features = ["test_tools"] }
 mockall = { workspace = true }
 slog-async = { workspace = true }
 slog-term = { workspace = true }

internal/mithril-dmq/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-era"
-version = "0.1.4"
+version = "0.1.5"
 authors.workspace = true
 documentation.workspace = true
 edition.workspace = true
@@ -21,5 +21,4 @@ serde_json = { workspace = true }
 thiserror = { workspace = true }
 
 [dev-dependencies]
-mithril-common = { path = "../../mithril-common", features = ["test_tools"] }
 tokio = { workspace = true, features = ["macros"] }

internal/mithril-era/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-metric"
-version = "0.1.18"
+version = "0.1.19"
 description = "Common tools to expose metrics."
 authors = { workspace = true }
 edition = { workspace = true }
@@ -22,7 +22,6 @@ slog = { workspace = true }
 tokio = { workspace = true }
 
 [dev-dependencies]
-mithril-common = { path = "../../mithril-common", features = ["test_tools"] }
 prometheus-parse = "0.2.5"
 slog-async = { workspace = true }
 slog-term = { workspace = true }

internal/mithril-metric/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-persistence"
-version = "0.2.58"
+version = "0.2.59"
 description = "Common types, interfaces, and utilities to persist data for Mithril nodes."
 authors = { workspace = true }
 edition = { workspace = true }
@@ -26,5 +26,4 @@ thiserror = { workspace = true }
 tokio = { workspace = true }
 
 [dev-dependencies]
-mithril-common = { path = "../../mithril-common", features = ["test_tools"] }
 tokio = { workspace = true, features = ["macros", "time"] }