docs: require unit tests in *_tests.rs files

AGENTS.md

@@ -11,7 +11,7 @@ Do not log provider queries, credentials, or result content. Provider credential
 arrive through sensitive module initialization and reinitialization config.
 
 Every public item needs rustdoc. Keep types and behavior in focused modules,
-with tests in neighboring `test.rs` files. Cover wire representations and real
+with tests in neighboring `*_tests.rs` files. Cover wire representations and real
 in-memory TinyBus calls. No placeholders, ignored tests, or lint exemptions.
 
 Run from repository root:
@@ -24,3 +24,28 @@ cargo test --all-features
 ```
 
 PRs go to the canonical upstream repository and should be ready for review.
+
+## Tests live in `*_tests.rs` files
+
+- Unit tests are never inline. Do not write a `#[cfg(test)] mod tests { ... }`
+  block in a source file. Put the tests in a sibling `<module>_tests.rs`
+  (`mod_tests.rs` beside a `mod.rs`, `lib_tests.rs` beside `lib.rs`) and declare
+  it at the bottom of the module:
+
+  ```rust
+  #[cfg(test)]
+  #[path = "foo_tests.rs"]
+  mod tests;
+  ```
+
+- The test file starts with `use super::*;` and carries no `#[cfg(test)]` of its
+  own. It is still a child module, so it reaches private items exactly as an
+  inline module did.
+- Name test files `<module>_tests.rs`; a second group for the same module is
+  `<module>_<topic>_tests.rs`. Never `test.rs`, `tests.rs` or `<module>_test.rs`.
+- Integration tests stay in the crate's `tests/` directory.
+- OpenHuman's `scripts/externalize-inline-tests.mjs <repo-root> --write` moves
+  inline test modules out mechanically; without `--write` it only reports.
+- Existing `test.rs` and `<module>_test.rs` files predate this rule. Rename each
+  to `<module>_tests.rs` (keep its `mod` name, add the `#[path]` attribute) the
+  next time you touch it.

crates/tinysearch-bus/src/search/catalog/test.rs

@@ -139,7 +139,7 @@ fn provider_roles_and_defaults_match_the_contract() {
         role_provider_tool(Role::Contents, "parallel"),
         Some("parallel_extract")
     );
-    assert!(provider_roles("unknown").is_empty());
+    assert_eq!(provider_roles("unknown").len(), 0);
     assert_eq!(provider_roles("gemini"), [Role::Answer]);
     assert_eq!(provider_roles("gemini_deep_research"), [Role::Answer]);
     assert_eq!(provider_roles("tinyfish"), [Role::Search, Role::Contents]);
@@ -307,10 +307,11 @@ fn roles_mode_without_backend_credential_drops_backend_providers() {
         listed.tools[1].parameters["properties"]["provider"]["enum"],
         json!(["tinyfish"])
     );
-    assert!(
+    assert_eq!(
         select_tools(&BTreeMap::new(), &config.presentation)
             .tools
-            .is_empty()
+            .len(),
+        0
     );
 }
 

crates/tinysearch-bus/src/search/test.rs

@@ -83,7 +83,7 @@ fn roles_and_role_lists_round_trip_as_snake_case() -> serde_json::Result<()> {
     assert_eq!(presentation.mode, PresentationMode::Roles);
     assert_eq!(presentation.roles[&Role::Search], ["brave", "exa"]);
     assert_eq!(presentation.roles[&Role::Answer], ["gemini"]);
-    assert!(presentation.roles[&Role::Contents].is_empty());
+    assert_eq!(presentation.roles[&Role::Contents].len(), 0);
     assert_eq!(
         serde_json::to_value(&presentation)?["roles"]["search"],
         serde_json::json!(["brave", "exa"])
@@ -103,7 +103,7 @@ fn role_response_fields_are_optional_on_the_wire() -> serde_json::Result<()> {
         "provider":"exa","results":[],"citations":[],"answer":null,"status":"empty"
     }))?;
     assert_eq!(legacy.role, None);
-    assert!(legacy.fallback_from.is_empty());
+    assert_eq!(legacy.fallback_from.len(), 0);
     let encoded = serde_json::to_value(&legacy)?;
     assert!(encoded.get("role").is_none());
     assert!(encoded.get("fallback_from").is_none());

crates/tinysearch/src/provider/direct/parallel/test.rs

@@ -391,7 +391,7 @@ fn all_tools_catalog_is_direct_only() -> std::result::Result<(), Box<dyn std::er
         .ok_or("missing provider")?
         .route = ProviderRoute::Backend;
     let service = SearchService::with_providers(config, builtins());
-    assert!(service.list_tools().tools.is_empty());
+    assert_eq!(service.list_tools().tools.len(), 0);
     Ok(())
 }
 

crates/tinysearch/src/provider/direct/tinyfish/test.rs

@@ -20,7 +20,7 @@ fn search_is_a_get_with_the_documented_query_fields() -> TestResult<()> {
     )?;
     assert_eq!(method, Method::GET);
     assert_eq!(base, SEARCH_BASE);
-    assert!(path.is_empty());
+    assert_eq!(path.len(), 0);
     assert!(body.is_none());
     assert_eq!(
         params,
@@ -48,8 +48,8 @@ fn fetch_posts_urls_and_format_only() -> TestResult<()> {
     )?;
     assert_eq!(method, Method::POST);
     assert_eq!(base, FETCH_BASE);
-    assert!(path.is_empty());
-    assert!(params.is_empty());
+    assert_eq!(path.len(), 0);
+    assert_eq!(params.len(), 0);
     assert_eq!(
         body,
         Some(json!({"urls":["https://a.example","https://b.example"],"format":"html"}))

crates/tinysearch/src/search/roles/test.rs

@@ -164,7 +164,7 @@ async fn search_uses_the_first_provider_and_translates_arguments() -> Result<()>
         .await?;
     assert_eq!(response.provider, "exa");
     assert_eq!(response.role, Some(Role::Search));
-    assert!(response.fallback_from.is_empty());
+    assert_eq!(response.fallback_from.len(), 0);
     let sent = fixture.calls("exa");
     assert_eq!(sent.len(), 1);
     assert_eq!(sent[0].name, "exa_search");
@@ -216,7 +216,7 @@ async fn invalid_arguments_do_not_fall_back() {
             "provider returned HTTP 400".into()
         ))
     );
-    assert!(fixture.calls("brave").is_empty());
+    assert_eq!(fixture.calls("brave").len(), 0);
 }
 
 #[tokio::test]
@@ -248,8 +248,8 @@ async fn explicit_provider_is_used_alone_without_fallback() -> Result<()> {
         ))
         .await;
     assert_eq!(result.err(), Some(Error::InsufficientBalance));
-    assert!(fixture.calls("exa").is_empty());
-    assert!(fixture.calls("tavily").is_empty());
+    assert_eq!(fixture.calls("exa").len(), 0);
+    assert_eq!(fixture.calls("tavily").len(), 0);
 
     let response = fixture
         .service
@@ -259,7 +259,7 @@ async fn explicit_provider_is_used_alone_without_fallback() -> Result<()> {
         ))
         .await?;
     assert_eq!(response.provider, "tavily");
-    assert!(fixture.calls("exa").is_empty());
+    assert_eq!(fixture.calls("exa").len(), 0);
     Ok(())
 }
 
@@ -296,7 +296,7 @@ async fn role_arguments_are_validated_before_dispatch() {
             .err(),
         Some(Error::UnavailableTool("exa_search".into()))
     );
-    assert!(fixture.calls("exa").is_empty());
+    assert_eq!(fixture.calls("exa").len(), 0);
 }
 
 #[tokio::test]
@@ -312,7 +312,7 @@ async fn quick_answers_skip_deep_research() -> Result<()> {
     assert_eq!(fixture.calls("gemini")[0].name, "gemini_agentic_search");
     assert_eq!(fixture.calls("exa")[0].name, "exa_answer");
     assert_eq!(fixture.calls("exa")[0].arguments, json!({"query":"why"}));
-    assert!(fixture.calls("gemini_deep_research").is_empty());
+    assert_eq!(fixture.calls("gemini_deep_research").len(), 0);
     Ok(())
 }
 
@@ -368,7 +368,7 @@ async fn explicit_quick_depth_is_rejected_when_only_deep_research_is_usable() {
         ))
         .await;
     assert_eq!(result.err(), Some(Error::InvalidArguments));
-    assert!(fixture.calls("gemini_deep_research").is_empty());
+    assert_eq!(fixture.calls("gemini_deep_research").len(), 0);
 }
 
 #[tokio::test]
@@ -564,7 +564,7 @@ async fn parallel_is_never_usable_on_the_backend_route() {
             parallel.route = ProviderRoute::Backend;
         }
     });
-    assert!(fixture.service.list_tools().tools.is_empty());
+    assert_eq!(fixture.service.list_tools().tools.len(), 0);
     for (tool, arguments) in [
         (tools::WEB_SEARCH, json!({"query":"rust"})),
         (tools::WEB_ANSWER, json!({"query":"why"})),
@@ -582,7 +582,7 @@ async fn parallel_is_never_usable_on_the_backend_route() {
             Some(Error::UnavailableTool(tool.into()))
         );
     }
-    assert!(fixture.calls("parallel").is_empty());
+    assert_eq!(fixture.calls("parallel").len(), 0);
 }
 
 #[tokio::test]
@@ -602,7 +602,7 @@ async fn role_calls_fall_back_into_parallel() -> Result<()> {
         .await?;
     assert_eq!(response.provider, "parallel");
     assert_eq!(response.fallback_from, ["exa", "brave", "tavily"]);
-    assert!(fixture.calls("tinyfish").is_empty());
+    assert_eq!(fixture.calls("tinyfish").len(), 0);
 
     let response = fixture
         .service
@@ -650,7 +650,7 @@ async fn deep_answers_skip_parallel() -> Result<()> {
         .await;
     assert!(matches!(result, Err(Error::ProviderUnavailable(_))));
     assert_eq!(fixture.calls("gemini_deep_research").len(), 1);
-    assert!(fixture.calls("parallel").is_empty());
+    assert_eq!(fixture.calls("parallel").len(), 0);
 
     assert_eq!(
         fixture
@@ -663,7 +663,7 @@ async fn deep_answers_skip_parallel() -> Result<()> {
             .err(),
         Some(Error::InvalidArguments)
     );
-    assert!(fixture.calls("parallel").is_empty());
+    assert_eq!(fixture.calls("parallel").len(), 0);
 
     let response = fixture
         .service

crates/tinysearch/src/search/test.rs

@@ -186,7 +186,7 @@ async fn router_never_dispatches_search_to_a_non_search_provider() {
     )]
     .into();
     let service = SearchService::with_providers(config, providers);
-    assert!(service.list_tools().tools.is_empty());
+    assert_eq!(service.list_tools().tools.len(), 0);
     let result = service
         .execute_tool(ExecuteToolRequest {
             name: "search".into(),
@@ -223,7 +223,7 @@ async fn rejects_unadvertised_tool_and_invalid_arguments() {
 fn disabling_search_suppresses_tools() {
     let mut service = service(PresentationMode::AllTools);
     service.config.enabled = false;
-    assert!(service.list_tools().tools.is_empty());
+    assert_eq!(service.list_tools().tools.len(), 0);
 }
 
 #[tokio::test]
@@ -303,11 +303,12 @@ fn router_hides_unknown_providers() {
         Arc::new(MockProvider) as Arc<dyn SearchProvider>,
     )]
     .into();
-    assert!(
+    assert_eq!(
         SearchService::with_providers(config, providers)
             .list_tools()
             .tools
-            .is_empty()
+            .len(),
+        0
     );
 }
 
@@ -368,11 +369,12 @@ fn direct_provider_without_credential_is_hidden() {
         .insert("tinyfish".into(), ProviderConfig::default());
     let mut providers: BTreeMap<String, Arc<dyn SearchProvider>> = BTreeMap::new();
     providers.insert("tinyfish".into(), Arc::new(Keyed));
-    assert!(
+    assert_eq!(
         SearchService::with_providers(config.clone(), providers.clone())
             .list_tools()
             .tools
-            .is_empty()
+            .len(),
+        0
     );
     config.providers.insert(
         "tinyfish".into(),

crates/tinysearch/src/tinybus_module/test.rs

@@ -36,7 +36,7 @@ async fn empty_configuration_serves_no_tools_and_rejects_execution() -> tinybus:
     let client = Connection::connect(bus.connect().await?).await?;
     let proxy = client.proxy(names::INTERFACE, names::OBJECT_PATH, names::INTERFACE)?;
     let listed: ListToolsResponse = proxy.call(names::methods::LIST_TOOLS, ()).await?;
-    assert!(listed.tools.is_empty());
+    assert_eq!(listed.tools.len(), 0);
     let result = proxy
         .call::<ExecuteToolResponse>(
             names::methods::EXECUTE_TOOL,
@@ -84,10 +84,10 @@ fn builtins_discover_and_reinitialize_from_private_configuration() {
         provider.enabled = false;
     }
     let refreshed = SearchService::with_providers(config.clone(), crate::provider::builtins());
-    assert!(refreshed.list_tools().tools.is_empty());
+    assert_eq!(refreshed.list_tools().tools.len(), 0);
     config.enabled = false;
     let disabled = SearchService::with_providers(config, crate::provider::builtins());
-    assert!(disabled.list_tools().tools.is_empty());
+    assert_eq!(disabled.list_tools().tools.len(), 0);
 }
 
 #[tokio::test]

crates/tinysearch/tests/public_api.rs

@@ -4,10 +4,11 @@ use tinysearch::{SearchConfig, SearchService, names};
 #[test]
 fn host_can_discover_search_interface() {
     assert_eq!(names::methods::LIST_TOOLS, "ListTools");
-    assert!(
+    assert_eq!(
         SearchService::with_providers(SearchConfig::default(), BTreeMap::new())
             .list_tools()
             .tools
-            .is_empty()
+            .len(),
+        0
     );
 }