Feat/test operations

README.md

@@ -81,6 +81,14 @@ npm install ctrf
 - [organizeTestsBySuite](docs/functions/organizeTestsBySuite.md)
 - [traverseTree](docs/functions/traverseTree.md)
 
+### Test Operations Methods
+
+- [findTestById](docs/functions/findTestById.md)
+- [generateTestIdFromProperties](docs/functions/generateTestIdFromProperties.md)
+- [getTestId](docs/functions/getTestId.md)
+- [setTestId](docs/functions/setTestId.md)
+- [setTestIdsForReport](docs/functions/setTestIdsForReport.md)
+
 ### Utility Types
 
 - [SortOrder](docs/enumerations/SortOrder.md) (enumeration)
@@ -89,6 +97,7 @@ npm install ctrf
 - [TreeOptions](docs/interfaces/TreeOptions.md)
 - [ValidationResult](docs/interfaces/ValidationResult.md)
 - [TreeTest](docs/type-aliases/TreeTest.md)
+- [CTRF\_NAMESPACE](docs/variables/CTRF_NAMESPACE.md)
 
 ## TypeScript Types
 

docs/README.md

@@ -50,6 +50,14 @@
 - [organizeTestsBySuite](functions/organizeTestsBySuite.md)
 - [traverseTree](functions/traverseTree.md)
 
+## Test Operations
+
+- [findTestById](functions/findTestById.md)
+- [generateTestIdFromProperties](functions/generateTestIdFromProperties.md)
+- [getTestId](functions/getTestId.md)
+- [setTestId](functions/setTestId.md)
+- [setTestIdsForReport](functions/setTestIdsForReport.md)
+
 ## Enumerations
 
 - [SortOrder](enumerations/SortOrder.md)
@@ -64,3 +72,7 @@
 ## Type Aliases
 
 - [TreeTest](type-aliases/TreeTest.md)
+
+## Variables
+
+- [CTRF\_NAMESPACE](variables/CTRF_NAMESPACE.md)

docs/functions/findTestById.md

@@ -0,0 +1,33 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / findTestById
+
+# Function: findTestById()
+
+> **findTestById**(`report`, `testId`): `undefined` \| [`Test`](../interfaces/Test.md)
+
+Defined in: src/methods/test-id.ts:84
+
+Finds a test by its ID in a report
+
+## Parameters
+
+### report
+
+[`Report`](../interfaces/Report.md)
+
+The CTRF report
+
+### testId
+
+`string`
+
+The test ID to search for
+
+## Returns
+
+`undefined` \| [`Test`](../interfaces/Test.md)
+
+The test object if found, undefined otherwise

docs/functions/generateTestIdFromProperties.md

@@ -0,0 +1,39 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / generateTestIdFromProperties
+
+# Function: generateTestIdFromProperties()
+
+> **generateTestIdFromProperties**(`name`, `suite?`, `filePath?`): `string`
+
+Defined in: src/methods/test-id.ts:95
+
+Generates a new test ID based on test properties (exposed utility)
+
+## Parameters
+
+### name
+
+`string`
+
+Test name
+
+### suite?
+
+`string`[]
+
+Test suite path
+
+### filePath?
+
+`string`
+
+Test file path
+
+## Returns
+
+`string`
+
+A deterministic UUID v5 string based on the properties

docs/functions/getTestId.md

@@ -0,0 +1,27 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / getTestId
+
+# Function: getTestId()
+
+> **getTestId**(`test`): `string`
+
+Defined in: src/methods/test-id.ts:61
+
+Gets the test ID from a test object, generating one if it doesn't exist
+
+## Parameters
+
+### test
+
+[`Test`](../interfaces/Test.md)
+
+The test object to get the ID from
+
+## Returns
+
+`string`
+
+The test ID

docs/functions/setTestId.md

@@ -0,0 +1,27 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / setTestId
+
+# Function: setTestId()
+
+> **setTestId**(`test`): [`Test`](../interfaces/Test.md)
+
+Defined in: src/methods/test-id.ts:49
+
+Sets a test ID for a test object based on its properties
+
+## Parameters
+
+### test
+
+[`Test`](../interfaces/Test.md)
+
+The test object to add an ID to
+
+## Returns
+
+[`Test`](../interfaces/Test.md)
+
+The test object with the ID set

docs/functions/setTestIdsForReport.md

@@ -0,0 +1,27 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / setTestIdsForReport
+
+# Function: setTestIdsForReport()
+
+> **setTestIdsForReport**(`report`): [`Report`](../interfaces/Report.md)
+
+Defined in: src/methods/test-id.ts:73
+
+Sets test IDs for all tests in a report
+
+## Parameters
+
+### report
+
+[`Report`](../interfaces/Report.md)
+
+The CTRF report
+
+## Returns
+
+[`Report`](../interfaces/Report.md)
+
+The report with test IDs set for all tests

docs/variables/CTRF_NAMESPACE.md

@@ -0,0 +1,15 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / CTRF\_NAMESPACE
+
+# Variable: CTRF\_NAMESPACE
+
+> `const` **CTRF\_NAMESPACE**: `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` = `'6ba7b810-9dad-11d1-80b4-00c04fd430c8'`
+
+Defined in: src/methods/test-id.ts:11
+
+The CTRF namespace UUID used for generating deterministic test IDs.
+This namespace ensures that all CTRF test IDs are generated consistently
+across different implementations and tools.

examples/test-id-example.md

@@ -0,0 +1,99 @@
+# Test ID Operations Example
+
+This example demonstrates how to use the new deterministic test ID functionality.
+
+```typescript
+import { 
+  setTestId, 
+  getTestId, 
+  setTestIdsForReport, 
+  findTestById,
+  generateTestIdFromProperties 
+} from 'ctrf'
+import type { Test, Report } from 'ctrf'
+
+// Example test object
+const test: Test = {
+  name: 'should authenticate user',
+  status: 'passed',
+  duration: 150,
+  suite: ['auth', 'login'],
+  filePath: 'src/auth/login.test.ts'
+}
+
+// Set a test ID (generates deterministic UUID based on properties)
+setTestId(test)
+console.log('Test ID:', test.id) // Always the same UUID for these properties!
+
+// Get a test ID (generates one if not present)
+const testId = getTestId(test)
+console.log('Test ID:', testId) // Same as above
+
+// Generate a test ID from properties - always deterministic!
+const customId = generateTestIdFromProperties(
+  'my test',
+  ['suite1', 'suite2'],
+  'my-test.ts'
+)
+console.log('Generated ID:', customId) // Always the same for these inputs
+
+// Demonstrate deterministic behavior
+const sameId = generateTestIdFromProperties(
+  'my test',
+  ['suite1', 'suite2'], 
+  'my-test.ts'
+)
+console.log('Same ID?', customId === sameId) // true!
+
+// Set IDs for all tests in a report
+const report: Report = {
+  reportFormat: 'CTRF',
+  specVersion: '1.0.0',
+  results: {
+    tool: { name: 'vitest' },
+    summary: {
+      tests: 2,
+      passed: 2,
+      failed: 0,
+      skipped: 0,
+      pending: 0,
+      other: 0,
+      start: Date.now(),
+      stop: Date.now() + 1000
+    },
+    tests: [
+      {
+        name: 'test 1',
+        status: 'passed',
+        duration: 100,
+        suite: ['unit'],
+        filePath: 'test1.ts'
+      },
+      {
+        name: 'test 2', 
+        status: 'passed',
+        duration: 200,
+        suite: ['integration'],
+        filePath: 'test2.ts'
+      }
+    ]
+  }
+}
+
+// Set IDs for all tests
+setTestIdsForReport(report)
+
+// Find a test by its ID
+const foundTest = findTestById(report, report.results.tests[0].id!)
+console.log('Found test:', foundTest?.name)
+```
+
+## Key Features
+
+1. **Deterministic UUIDs**: Same test properties always generate the same UUID
+2. **Proper UUID format**: Valid UUIDs that follow the standard format
+3. **Non-destructive**: Won't overwrite existing IDs
+4. **Property-based**: Uses test name, suite, and filePath for generation
+5. **Report-level operations**: Can process entire reports at once
+6. **Search functionality**: Find tests by their deterministic IDs
+7. **Consistent across runs**: Same test will always have the same ID

src/index.ts

@@ -49,6 +49,17 @@ export {
   getAllTests,
   getSuiteStats,
 } from './methods/tree-hierarchical-structure.js'
+/**
+ * @group Test Operations
+ */
+export {
+  setTestId,
+  getTestId,
+  setTestIdsForReport,
+  findTestById,
+  generateTestIdFromProperties,
+  CTRF_NAMESPACE,
+} from './methods/test-id.js'
 
 /**
  * @group Schema