Skip to content

Commit da416e8

Browse files
Ma11hewThomasMa11hewThomas
authored
Feat/test operations (#8)
* feat: add test operations
1 parent 880904f commit da416e8

File tree

14 files changed

+596
-1
lines changed

14 files changed

+596
-1
lines changed

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,14 @@ npm install ctrf
8181
- [organizeTestsBySuite](docs/functions/organizeTestsBySuite.md)
8282
- [traverseTree](docs/functions/traverseTree.md)
8383

84+
### Test Operations Methods
85+
86+
- [findTestById](docs/functions/findTestById.md)
87+
- [generateTestIdFromProperties](docs/functions/generateTestIdFromProperties.md)
88+
- [getTestId](docs/functions/getTestId.md)
89+
- [setTestId](docs/functions/setTestId.md)
90+
- [setTestIdsForReport](docs/functions/setTestIdsForReport.md)
91+
8492
### Utility Types
8593

8694
- [SortOrder](docs/enumerations/SortOrder.md) (enumeration)
@@ -89,6 +97,7 @@ npm install ctrf
8997
- [TreeOptions](docs/interfaces/TreeOptions.md)
9098
- [ValidationResult](docs/interfaces/ValidationResult.md)
9199
- [TreeTest](docs/type-aliases/TreeTest.md)
100+
- [CTRF\_NAMESPACE](docs/variables/CTRF_NAMESPACE.md)
92101

93102
## TypeScript Types
94103

‎docs/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,14 @@
5050
- [organizeTestsBySuite](functions/organizeTestsBySuite.md)
5151
- [traverseTree](functions/traverseTree.md)
5252

53+
## Test Operations
54+
55+
- [findTestById](functions/findTestById.md)
56+
- [generateTestIdFromProperties](functions/generateTestIdFromProperties.md)
57+
- [getTestId](functions/getTestId.md)
58+
- [setTestId](functions/setTestId.md)
59+
- [setTestIdsForReport](functions/setTestIdsForReport.md)
60+
5361
## Enumerations
5462

5563
- [SortOrder](enumerations/SortOrder.md)
@@ -64,3 +72,7 @@
6472
## Type Aliases
6573

6674
- [TreeTest](type-aliases/TreeTest.md)
75+
76+
## Variables
77+
78+
- [CTRF\_NAMESPACE](variables/CTRF_NAMESPACE.md)

‎docs/functions/findTestById.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / findTestById
6+
7+
# Function: findTestById()
8+
9+
> **findTestById**(`report`, `testId`): `undefined` \| [`Test`](../interfaces/Test.md)
10+
11+
Defined in: src/methods/test-id.ts:84
12+
13+
Finds a test by its ID in a report
14+
15+
## Parameters
16+
17+
### report
18+
19+
[`Report`](../interfaces/Report.md)
20+
21+
The CTRF report
22+
23+
### testId
24+
25+
`string`
26+
27+
The test ID to search for
28+
29+
## Returns
30+
31+
`undefined` \| [`Test`](../interfaces/Test.md)
32+
33+
The test object if found, undefined otherwise

‎docs/functions/generateTestIdFromProperties.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / generateTestIdFromProperties
6+
7+
# Function: generateTestIdFromProperties()
8+
9+
> **generateTestIdFromProperties**(`name`, `suite?`, `filePath?`): `string`
10+
11+
Defined in: src/methods/test-id.ts:95
12+
13+
Generates a new test ID based on test properties (exposed utility)
14+
15+
## Parameters
16+
17+
### name
18+
19+
`string`
20+
21+
Test name
22+
23+
### suite?
24+
25+
`string`[]
26+
27+
Test suite path
28+
29+
### filePath?
30+
31+
`string`
32+
33+
Test file path
34+
35+
## Returns
36+
37+
`string`
38+
39+
A deterministic UUID v5 string based on the properties

‎docs/functions/getTestId.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / getTestId
6+
7+
# Function: getTestId()
8+
9+
> **getTestId**(`test`): `string`
10+
11+
Defined in: src/methods/test-id.ts:61
12+
13+
Gets the test ID from a test object, generating one if it doesn't exist
14+
15+
## Parameters
16+
17+
### test
18+
19+
[`Test`](../interfaces/Test.md)
20+
21+
The test object to get the ID from
22+
23+
## Returns
24+
25+
`string`
26+
27+
The test ID

‎docs/functions/setTestId.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / setTestId
6+
7+
# Function: setTestId()
8+
9+
> **setTestId**(`test`): [`Test`](../interfaces/Test.md)
10+
11+
Defined in: src/methods/test-id.ts:49
12+
13+
Sets a test ID for a test object based on its properties
14+
15+
## Parameters
16+
17+
### test
18+
19+
[`Test`](../interfaces/Test.md)
20+
21+
The test object to add an ID to
22+
23+
## Returns
24+
25+
[`Test`](../interfaces/Test.md)
26+
27+
The test object with the ID set

‎docs/functions/setTestIdsForReport.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / setTestIdsForReport
6+
7+
# Function: setTestIdsForReport()
8+
9+
> **setTestIdsForReport**(`report`): [`Report`](../interfaces/Report.md)
10+
11+
Defined in: src/methods/test-id.ts:73
12+
13+
Sets test IDs for all tests in a report
14+
15+
## Parameters
16+
17+
### report
18+
19+
[`Report`](../interfaces/Report.md)
20+
21+
The CTRF report
22+
23+
## Returns
24+
25+
[`Report`](../interfaces/Report.md)
26+
27+
The report with test IDs set for all tests

‎docs/variables/CTRF_NAMESPACE.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[**CTRF v0.0.16**](../README.md)
2+
3+
***
4+
5+
[CTRF](../README.md) / CTRF\_NAMESPACE
6+
7+
# Variable: CTRF\_NAMESPACE
8+
9+
> `const` **CTRF\_NAMESPACE**: `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` = `'6ba7b810-9dad-11d1-80b4-00c04fd430c8'`
10+
11+
Defined in: src/methods/test-id.ts:11
12+
13+
The CTRF namespace UUID used for generating deterministic test IDs.
14+
This namespace ensures that all CTRF test IDs are generated consistently
15+
across different implementations and tools.

‎examples/test-id-example.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Test ID Operations Example
2+
3+
This example demonstrates how to use the new deterministic test ID functionality.
4+
5+
```typescript
6+
import {
7+
setTestId,
8+
getTestId,
9+
setTestIdsForReport,
10+
findTestById,
11+
generateTestIdFromProperties
12+
} from 'ctrf'
13+
import type { Test, Report } from 'ctrf'
14+
15+
// Example test object
16+
const test: Test = {
17+
name: 'should authenticate user',
18+
status: 'passed',
19+
duration: 150,
20+
suite: ['auth', 'login'],
21+
filePath: 'src/auth/login.test.ts'
22+
}
23+
24+
// Set a test ID (generates deterministic UUID based on properties)
25+
setTestId(test)
26+
console.log('Test ID:', test.id) // Always the same UUID for these properties!
27+
28+
// Get a test ID (generates one if not present)
29+
const testId = getTestId(test)
30+
console.log('Test ID:', testId) // Same as above
31+
32+
// Generate a test ID from properties - always deterministic!
33+
const customId = generateTestIdFromProperties(
34+
'my test',
35+
['suite1', 'suite2'],
36+
'my-test.ts'
37+
)
38+
console.log('Generated ID:', customId) // Always the same for these inputs
39+
40+
// Demonstrate deterministic behavior
41+
const sameId = generateTestIdFromProperties(
42+
'my test',
43+
['suite1', 'suite2'],
44+
'my-test.ts'
45+
)
46+
console.log('Same ID?', customId === sameId) // true!
47+
48+
// Set IDs for all tests in a report
49+
const report: Report = {
50+
reportFormat: 'CTRF',
51+
specVersion: '1.0.0',
52+
results: {
53+
tool: { name: 'vitest' },
54+
summary: {
55+
tests: 2,
56+
passed: 2,
57+
failed: 0,
58+
skipped: 0,
59+
pending: 0,
60+
other: 0,
61+
start: Date.now(),
62+
stop: Date.now() + 1000
63+
},
64+
tests: [
65+
{
66+
name: 'test 1',
67+
status: 'passed',
68+
duration: 100,
69+
suite: ['unit'],
70+
filePath: 'test1.ts'
71+
},
72+
{
73+
name: 'test 2',
74+
status: 'passed',
75+
duration: 200,
76+
suite: ['integration'],
77+
filePath: 'test2.ts'
78+
}
79+
]
80+
}
81+
}
82+
83+
// Set IDs for all tests
84+
setTestIdsForReport(report)
85+
86+
// Find a test by its ID
87+
const foundTest = findTestById(report, report.results.tests[0].id!)
88+
console.log('Found test:', foundTest?.name)
89+
```
90+
91+
## Key Features
92+
93+
1. **Deterministic UUIDs**: Same test properties always generate the same UUID
94+
2. **Proper UUID format**: Valid UUIDs that follow the standard format
95+
3. **Non-destructive**: Won't overwrite existing IDs
96+
4. **Property-based**: Uses test name, suite, and filePath for generation
97+
5. **Report-level operations**: Can process entire reports at once
98+
6. **Search functionality**: Find tests by their deterministic IDs
99+
7. **Consistent across runs**: Same test will always have the same ID

‎src/index.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,17 @@ export {
4949
getAllTests,
5050
getSuiteStats,
5151
} from './methods/tree-hierarchical-structure.js'
52+
/**
53+
* @group Test Operations
54+
*/
55+
export {
56+
setTestId,
57+
getTestId,
58+
setTestIdsForReport,
59+
findTestById,
60+
generateTestIdFromProperties,
61+
CTRF_NAMESPACE,
62+
} from './methods/test-id.js'
5263

5364
/**
5465
* @group Schema

0 commit comments

Comments
 (0)