From 4f2068bb9d6adb540ec284de557ca7e2a55d0219 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 17 Dec 2025 07:40:53 -0600
Subject: [PATCH] docs: Clarify that names must be unique

See #166
---
 crates/libtest-json/event.schema.json | 4 ++++
 crates/libtest-json/src/event.rs      | 4 ++++
 crates/libtest2-harness/src/case.rs   | 2 ++
 crates/libtest2-mimic/src/lib.rs      | 3 +++
 4 files changed, 13 insertions(+)

diff --git a/crates/libtest-json/event.schema.json b/crates/libtest-json/event.schema.json
index f0fafd1..68c0df0 100644
--- a/crates/libtest-json/event.schema.json
+++ b/crates/libtest-json/event.schema.json
@@ -139,6 +139,7 @@
       "type": "object",
       "properties": {
         "name": {
+          "description": "An identifier that is unique across the entire run",
           "type": "string"
         },
         "mode": {
@@ -197,6 +198,7 @@
       "type": "object",
       "properties": {
         "name": {
+          "description": "An identifier that is unique across the entire run",
           "type": "string"
         },
         "elapsed_s": {
@@ -225,6 +227,7 @@
       "type": "object",
       "properties": {
         "name": {
+          "description": "An identifier that is unique across the entire run",
           "type": "string"
         },
         "kind": {
@@ -256,6 +259,7 @@
       "type": "object",
       "properties": {
         "name": {
+          "description": "An identifier that is unique across the entire run",
           "type": "string"
         },
         "elapsed_s": {
diff --git a/crates/libtest-json/src/event.rs b/crates/libtest-json/src/event.rs
index 5a7e7bc..7913735 100644
--- a/crates/libtest-json/src/event.rs
+++ b/crates/libtest-json/src/event.rs
@@ -123,6 +123,7 @@ impl DiscoverStart {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 pub struct DiscoverCase {
+    /// An identifier that is unique across the entire run
     pub name: String,
     #[cfg_attr(
         feature = "serde",
@@ -265,6 +266,7 @@ impl RunStart {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 pub struct CaseStart {
+    /// An identifier that is unique across the entire run
     pub name: String,
     #[cfg_attr(
         feature = "serde",
@@ -308,6 +310,7 @@ impl CaseStart {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 pub struct CaseMessage {
+    /// An identifier that is unique across the entire run
     pub name: String,
     pub kind: MessageKind,
     #[cfg_attr(
@@ -369,6 +372,7 @@ impl CaseMessage {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 pub struct CaseComplete {
+    /// An identifier that is unique across the entire run
     pub name: String,
     #[cfg_attr(
         feature = "serde",
diff --git a/crates/libtest2-harness/src/case.rs b/crates/libtest2-harness/src/case.rs
index 98c1849..ac9930b 100644
--- a/crates/libtest2-harness/src/case.rs
+++ b/crates/libtest2-harness/src/case.rs
@@ -6,6 +6,8 @@ pub trait Case: Send + Sync + 'static {
     /// By convention this follows the rules for rust paths; i.e., it should be a series of
     /// identifiers separated by double colons. This way if some test runner wants to arrange the
     /// tests hierarchically it may.
+    ///
+    /// Must be unique across the entire test run.
     fn name(&self) -> &str;
     fn kind(&self) -> TestKind;
     fn source(&self) -> Option<&Source>;
diff --git a/crates/libtest2-mimic/src/lib.rs b/crates/libtest2-mimic/src/lib.rs
index 474380c..12e9c56 100644
--- a/crates/libtest2-mimic/src/lib.rs
+++ b/crates/libtest2-mimic/src/lib.rs
@@ -131,6 +131,9 @@ pub struct Trial {
 }
 
 impl Trial {
+    /// Define a test case
+    ///
+    /// `name` must be unique across the entire test run.
     pub fn test(
         name: impl Into<String>,
         runner: impl Fn(RunContext<'_>) -> Result<(), RunError> + Send + Sync + 'static,