diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c02aec..b9e396f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,6 +63,7 @@ To set up the project for local development: ``` 5. **Build the package**: + ```bash npm run build ``` diff --git a/README.md b/README.md index 99c7110..c01f89f 100644 --- a/README.md +++ b/README.md @@ -26,30 +26,30 @@ npm install ctrf ## Quick Start ```typescript -import { ReportBuilder, TestBuilder, validateStrict } from 'ctrf' +import { ReportBuilder, TestBuilder, validateStrict } from "ctrf"; // Build a report using the fluent API const report = new ReportBuilder() - .tool({ name: 'jest', version: '29.0.0' }) - .addTest( - new TestBuilder() - .name('should add numbers') - .status('passed') - .duration(150) - .build() - ) - .addTest( - new TestBuilder() - .name('should handle errors') - .status('failed') - .duration(200) - .message('Expected 5 but got 4') - .build() - ) - .build() + .tool({ name: "jest", version: "29.0.0" }) + .addTest( + new TestBuilder() + .name("should add numbers") + .status("passed") + .duration(150) + .build(), + ) + .addTest( + new TestBuilder() + .name("should handle errors") + .status("failed") + .duration(200) + .message("Expected 5 but got 4") + .build(), + ) + .build(); // Validate the report -validateStrict(report) +validateStrict(report); ``` ## API Reference @@ -61,75 +61,85 @@ validateStrict(report) Full TypeScript types are provided for all CTRF entities. ```typescript -import type { CTRFReport, Test } from 'ctrf' - -const report: CTRFReport = { /* ... */ } -const test: Test = { /* ... */ } +import type { CTRFReport, Test } from "ctrf"; + +const report: CTRFReport = { + /* ... */ +}; +const test: Test = { + /* ... */ +}; ``` ### Validation ```typescript -import { isValid, validate, validateStrict, isCTRFReport, ValidationError } from 'ctrf' +import { + isValid, + validate, + validateStrict, + isCTRFReport, + ValidationError, +} from "ctrf"; // Quick validation (returns boolean) if (isValid(report)) { - console.log('Report is valid') + console.log("Report is valid"); } // Detailed validation (returns ValidationResult) -const result = validate(report) +const result = validate(report); if (!result.valid) { - result.errors?.forEach(err => console.error(err.message)) + result.errors?.forEach((err) => console.error(err.message)); } // Validate against a published historical schema -const historicalResult = validate(report, { specVersion: '0.0.2' }) +const historicalResult = validate(report, { specVersion: "0.0.2" }); // `latest` is an alias for the current published specification -validateStrict(report, { specVersion: 'latest' }) +validateStrict(report, { specVersion: "latest" }); // Strict validation (throws on invalid) try { - validateStrict(report) + validateStrict(report); } catch (error) { - if (error instanceof ValidationError) { - console.error('Invalid report:', error.errors) - } + if (error instanceof ValidationError) { + console.error("Invalid report:", error.errors); + } } // Type guards if (isCTRFReport(data)) { - // data is typed as CTRFReport + // data is typed as CTRFReport } ``` ### Building Reports ```typescript -import { ReportBuilder, TestBuilder } from 'ctrf' +import { ReportBuilder, TestBuilder } from "ctrf"; // ReportBuilder - fluent API for constructing reports const report = new ReportBuilder() - .runId('run-2026-08-13') - .tool({ name: 'vitest', version: '1.0.0' }) - .environment({ osPlatform: 'linux', shardId: 'shard-1-of-4' }) - .addTest(/* ... */) - .build() + .runId("run-2026-08-13") + .tool({ name: "vitest", version: "1.0.0" }) + .environment({ osPlatform: "linux", shardId: "shard-1-of-4" }) + .addTest(/* ... */) + .build(); // TestBuilder - fluent API for constructing tests const test = new TestBuilder() - .testId('authentication/login') - .executionId('execution-123') - .attemptId('attempt-1') - .name('User login test') - .status('passed') - .duration(1500) - .suite(['Authentication', 'Login']) - .tags(['smoke', 'critical']) - .filePath('tests/auth/login.test.ts') - .browser('chrome') - .build() + .testId("authentication/login") + .executionId("execution-123") + .attemptId("attempt-1") + .name("User login test") + .status("passed") + .duration(1500) + .suite(["Authentication", "Login"]) + .tags(["smoke", "critical"]) + .filePath("tests/auth/login.test.ts") + .browser("chrome") + .build(); ``` ### Retry Histories @@ -141,14 +151,24 @@ of history entries. ```typescript const flakyTest = new TestBuilder() - .name('eventually succeeds') - .attemptId('attempt-3') - .status('passed') // Final attempt - .duration(120) - .addAttemptHistoryEntry({ attempt: 1, attemptId: 'attempt-1', status: 'failed', duration: 80 }) - .addAttemptHistoryEntry({ attempt: 2, attemptId: 'attempt-2', status: 'failed', duration: 90 }) - .flaky() - .build() + .name("eventually succeeds") + .attemptId("attempt-3") + .status("passed") // Final attempt + .duration(120) + .addAttemptHistoryEntry({ + attempt: 1, + attemptId: "attempt-1", + status: "failed", + duration: 80, + }) + .addAttemptHistoryEntry({ + attempt: 2, + attemptId: "attempt-2", + status: "failed", + duration: 90, + }) + .flaky() + .build(); // flakyTest.retries === 2 // flakyTest.retryAttempts contains attempts 1 and 2; the final attempt is 3. @@ -160,86 +180,84 @@ const flakyTest = new TestBuilder() ### Parsing Reports ```typescript -import { parse, stringify } from 'ctrf' +import { parse, stringify } from "ctrf"; // Parse from string -const parsed = parse(jsonString) +const parsed = parse(jsonString); // Stringify with formatting -const json = stringify(report, { pretty: true, indent: 2 }) +const json = stringify(report, { pretty: true, indent: 2 }); ``` ### Filtering & Querying ```typescript -import { filterTests, findTest } from 'ctrf' +import { filterTests, findTest } from "ctrf"; // Filter by criteria const filtered = filterTests(report, { - status: 'failed', - suite: 'Authentication', - tags: ['smoke'], -}) + status: "failed", + suite: "Authentication", + tags: ["smoke"], +}); // Find specific test -const test = findTest(report, { name: 'login test' }) -const testById = findTest(report, { id: 'test-uuid' }) +const test = findTest(report, { name: "login test" }); +const testById = findTest(report, { id: "test-uuid" }); ``` ### Merging Reports ```typescript -import { merge } from 'ctrf' +import { merge } from "ctrf"; // Merge multiple reports into one const merged = merge([report1, report2, report3], { - deduplicateTests: true, // Remove duplicate tests by ID -}) + deduplicateTests: true, // Remove duplicate tests by ID +}); ``` ### ID Generation ```typescript -import { generateTestId, generateReportId } from 'ctrf' +import { generateTestId, generateReportId } from "ctrf"; // Generate deterministic test ID from properties const testId = generateTestId({ - name: 'should add numbers', - suite: ['Math', 'Addition'], - filePath: 'tests/math.test.ts', -}) + name: "should add numbers", + suite: ["Math", "Addition"], + filePath: "tests/math.test.ts", +}); // Generate random report ID -const reportId = generateReportId() +const reportId = generateReportId(); ``` ### Insights & Analytics ```typescript -import { addInsights, isTestFlaky } from 'ctrf' +import { addInsights, isTestFlaky } from "ctrf"; // Enrich a report with insights from historical data -const enriched = addInsights( - currentReport, - historicalReports, - { baseline: baselineReport } -) +const enriched = addInsights(currentReport, historicalReports, { + baseline: baselineReport, +}); // Access insights -console.log(enriched.insights?.passRate) // { current: 0.95, baseline: 0.90, change: 0.05 } -console.log(enriched.insights?.flakyRate) // { current: 0.02, baseline: 0.05, change: -0.03 } +console.log(enriched.insights?.passRate); // { current: 0.95, baseline: 0.90, change: 0.05 } +console.log(enriched.insights?.flakyRate); // { current: 0.02, baseline: 0.05, change: -0.03 } // Check if a test is flaky -const isFlaky = isTestFlaky(test) +const isFlaky = isTestFlaky(test); ``` ### Summary Calculation ```typescript -import { calculateSummary } from 'ctrf' +import { calculateSummary } from "ctrf"; // Calculate summary from tests -const summary = calculateSummary(tests) +const summary = calculateSummary(tests); // { tests: 10, passed: 8, failed: 1, skipped: 1, pending: 0, other: 0, ... } ``` @@ -247,55 +265,60 @@ const summary = calculateSummary(tests) ```typescript import { - REPORT_FORMAT, - CURRENT_SPEC_VERSION, - SUPPORTED_SPEC_VERSIONS, - TEST_STATUSES, - CTRF_NAMESPACE, -} from 'ctrf' - -REPORT_FORMAT // 'CTRF' -CURRENT_SPEC_VERSION // '0.2.0' -SUPPORTED_SPEC_VERSIONS // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0', '0.2.0'] -TEST_STATUSES // ['passed', 'failed', 'skipped', 'pending', 'other'] -CTRF_NAMESPACE // UUID namespace for deterministic IDs + REPORT_FORMAT, + CURRENT_SPEC_VERSION, + SUPPORTED_SPEC_VERSIONS, + TEST_STATUSES, + CTRF_NAMESPACE, +} from "ctrf"; + +REPORT_FORMAT; // 'CTRF' +CURRENT_SPEC_VERSION; // '0.2.0' +SUPPORTED_SPEC_VERSIONS; // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0', '0.2.0'] +TEST_STATUSES; // ['passed', 'failed', 'skipped', 'pending', 'other'] +CTRF_NAMESPACE; // UUID namespace for deterministic IDs ``` ### Error Handling ```typescript -import { validateStrict, ValidationError, ParseError } from 'ctrf' +import { validateStrict, ValidationError, ParseError } from "ctrf"; try { - validateStrict(report) + validateStrict(report); } catch (error) { - if (error instanceof ValidationError) { - console.error('CTRF validation failed:', error.errors) - } + if (error instanceof ValidationError) { + console.error("CTRF validation failed:", error.errors); + } } try { - const parsed = parse(jsonString) + const parsed = parse(jsonString); } catch (error) { - if (error instanceof ParseError) { - console.error('Invalid JSON:', error.message) - } + if (error instanceof ParseError) { + console.error("Invalid JSON:", error.message); + } } ``` ### Schema Access ```typescript -import { schema, getSchema, getCurrentSpecVersion, getSupportedSpecVersions } from 'ctrf' +import { + schema, + getSchema, + getCurrentSpecVersion, + getSupportedSpecVersions, +} from "ctrf"; // Get the current JSON Schema -console.log(schema) +console.log(schema); // Get schemas for a specific version or the latest published specification -const v0_0_2Schema = getSchema('0.0.2') -const latestSchema = getSchema('latest') +const v0_0_2Schema = getSchema("0.0.2"); +const latestSchema = getSchema("latest"); // Get version info -const version = getCurrentSpecVersion() // '0.2.0' -const supported = getSupportedSpecVersions() // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0', '0.2.0'] +const version = getCurrentSpecVersion(); // '0.2.0' +const supported = getSupportedSpecVersions(); // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0', '0.2.0'] ``` diff --git a/biome.json b/biome.json index 03ba91b..d125649 100644 --- a/biome.json +++ b/biome.json @@ -1,5 +1,5 @@ { - "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json", + "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", diff --git a/package-lock.json b/package-lock.json index 2386661..815beeb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,7 +19,7 @@ }, "devDependencies": { "@arethetypeswrong/cli": "0.18.5", - "@biomejs/biome": "2.5.15", + "@biomejs/biome": "2.6.4", "@d2t/vitest-ctrf-json-reporter": "1.3.0", "@types/node": "26.6.6", "@types/yargs": "17.0.35", @@ -159,9 +159,9 @@ } }, "node_modules/@biomejs/biome": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.15.tgz", - "integrity": "sha512-WZTW4slm/pdkh92K6t/3aEN++44JD1PQ7squ7RCMLI1flHGl43DVOIGXvCjHiZgBMO1V4uYxoFNtqrIA4qGuIQ==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.6.4.tgz", + "integrity": "sha512-8sKKwaNW4ot22awZ3lBjwWLHnUFXgXnrBPYS2gNlBAXRbDC++7kqjK2H7dR/FgCDtPvO1xfKpgEhJkGxAKYkxA==", "dev": true, "license": "MIT OR Apache-2.0", "bin": { @@ -175,20 +175,56 @@ "url": "https://opencollective.com/biome" }, "optionalDependencies": { - "@biomejs/cli-darwin-arm64": "2.5.15", - "@biomejs/cli-darwin-x64": "2.5.15", - "@biomejs/cli-linux-arm64": "2.5.15", - "@biomejs/cli-linux-arm64-musl": "2.5.15", - "@biomejs/cli-linux-x64": "2.5.15", - "@biomejs/cli-linux-x64-musl": "2.5.15", - "@biomejs/cli-win32-arm64": "2.5.15", - "@biomejs/cli-win32-x64": "2.5.15" + "@biomejs/cli-android-arm64": "2.6.4", + "@biomejs/cli-android-x64": "2.6.4", + "@biomejs/cli-darwin-arm64": "2.6.4", + "@biomejs/cli-darwin-x64": "2.6.4", + "@biomejs/cli-linux-arm64": "2.6.4", + "@biomejs/cli-linux-arm64-musl": "2.6.4", + "@biomejs/cli-linux-x64": "2.6.4", + "@biomejs/cli-linux-x64-musl": "2.6.4", + "@biomejs/cli-win32-arm64": "2.6.4", + "@biomejs/cli-win32-x64": "2.6.4" + } + }, + "node_modules/@biomejs/cli-android-arm64": { + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-android-arm64/-/cli-android-arm64-2.6.4.tgz", + "integrity": "sha512-jwrwigP4tBcHxzuV8izioX/BOUhJL/4e2rNSOE5nCjBkVC018LQAQUGiH+CNkFYvLtQ1dcZo5/xXERmaAGc7JQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-android-x64": { + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-android-x64/-/cli-android-x64-2.6.4.tgz", + "integrity": "sha512-HdGInPJ4nZFwHxzvEtcp2nmSBtUyJrurmtIK43upFckuS3+ZqVM05HtsxQWnqGsuy/pxckIAjyKWlEKRlBXUyA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.21.3" } }, "node_modules/@biomejs/cli-darwin-arm64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.15.tgz", - "integrity": "sha512-BZVzFhJ/mUvTLMYbc9x6el0o2Uv5zP7bACYyhFb6fSc1giroXm7PL0a5KqMJ9F+/BnkYRjagD/ROSDVOZ6eapg==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.6.4.tgz", + "integrity": "sha512-0VvcUz46wbg59Q4TZ59KkIjDJrxEyu4Eoe79+F4SChxoWe+W7AEyIp6F5r72C9+p6MsB6dIovnZt1D30lGM3XA==", "cpu": [ "arm64" ], @@ -203,9 +239,9 @@ } }, "node_modules/@biomejs/cli-darwin-x64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.15.tgz", - "integrity": "sha512-V5Kw63V+fVGNFhFrizDxMbGXAzZCh8kYzJpy3GI6gTapWDg7bZK9oYC9CbVgQSEdTnupz0U5Efz8Ev+5vdBBXw==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.6.4.tgz", + "integrity": "sha512-fxmvkF81srlS3DiMyfm+aG3J0eG+6/BjaxRyjy57KbLSafnq0PO+hHfVWmtH2ty0S7nm6yDXBRwySfFeaRJKRQ==", "cpu": [ "x64" ], @@ -220,9 +256,9 @@ } }, "node_modules/@biomejs/cli-linux-arm64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.15.tgz", - "integrity": "sha512-XaG7P7eeSLYETD3K9grfB0mQmpLQZjygdbsxekWBJAg4am79fGAtRpfRyNnTvXB2fZFNnJZG3nXm7HBat0+VUw==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.6.4.tgz", + "integrity": "sha512-6+bK1Y/evmIUiJr7auertuMbiaYVicJhqA1bZyL47lCMWugv8l0gFQCqvR/gN1vZMHYm+HwoTKgeMxdNFCoQTg==", "cpu": [ "arm64" ], @@ -240,9 +276,9 @@ } }, "node_modules/@biomejs/cli-linux-arm64-musl": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.15.tgz", - "integrity": "sha512-tGzZUTcJCV7tj5Adh/Gn6nR4MycqA3iohq2LEcrarAgRBkU0h0OKd2UzCRkOsOYOuUGaUJb4YmqRqyy2feGGSw==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.6.4.tgz", + "integrity": "sha512-31ZaH/MHqPX+O+evRwRrCHQ8W5/9adY+/eMytGGWZnRx1T41QsWIF09+/WujynLBhWZUxNGS5CtsWLwgOFTAyg==", "cpu": [ "arm64" ], @@ -260,9 +296,9 @@ } }, "node_modules/@biomejs/cli-linux-x64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.15.tgz", - "integrity": "sha512-xE4iEW/3LqlYj9GFgGrFsFSH51dEEpUbYWBfeOv0q87WkUDxK2o/HhreSb7qMJqck70RVM6Lg96hgedcAYcOkA==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.6.4.tgz", + "integrity": "sha512-tbFZMdL6dP/ws4edXxYG9WhvaVa1ZDzL4G5DzahnWW7Psib9H+VTdyU4XXVxpJk5j/nYZroSbvSNyYlpW3yCIw==", "cpu": [ "x64" ], @@ -280,9 +316,9 @@ } }, "node_modules/@biomejs/cli-linux-x64-musl": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.15.tgz", - "integrity": "sha512-IlxUcyxilVGPsE008x13pWdkTbU3nQpP2i9b5UrbOYj6goBkKsRX1XB7yJLcV+O1H9LBchIIm4adOaVLZBX0ZQ==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.6.4.tgz", + "integrity": "sha512-bomSa2XdQAGGj6Cwdm4M13qE+lN9+AOlW8KtI4hdyVyRRF/Z71qPAi95T4wtdZK0QpBbkTW8hgbZZCwPi4xzIw==", "cpu": [ "x64" ], @@ -300,9 +336,9 @@ } }, "node_modules/@biomejs/cli-win32-arm64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.15.tgz", - "integrity": "sha512-2kPKzhNlm8C+Ru3GcO0Me2ODkCBLrVOUNuyi84RJyWDVKAA4+Kjj3jMjL938lF6BRfvltC4vB2nPY9SvN51Ovg==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.6.4.tgz", + "integrity": "sha512-eCsqt8Ma3eVap+oyJCDnJZH60SIU464B66n3y38EUTJdM1T/HfZol1FJC9vb+sHToX0ix8XzqPcwJnOzyAJz0g==", "cpu": [ "arm64" ], @@ -317,9 +353,9 @@ } }, "node_modules/@biomejs/cli-win32-x64": { - "version": "2.5.15", - "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.15.tgz", - "integrity": "sha512-yAzh4UqEImV6Hcy0zjUqNfJAsUhoD64FBQCdTG8Md/Z2wQeVP/ZmJ3XRYAs1g8J9fjTFyl2fCtc5FB5til47+g==", + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.6.4.tgz", + "integrity": "sha512-pYsMy5AThiHFOZAsngg8qN4PurM6nInKBhVX7sbj3eNpRQqo1Hb0MgCwPL7VqVMrmcEEMj9Ks3qbkallR65e8g==", "cpu": [ "x64" ], @@ -3512,20 +3548,6 @@ "node": ">=0.10.0" } }, - "node_modules/obug": { - "version": "2.2.1", - "resolved": "https://registry.npmjs.org/obug/-/obug-2.2.1.tgz", - "integrity": "sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q==", - "dev": true, - "funding": [ - "https://github.com/sponsors/sxzz", - "https://opencollective.com/debug" - ], - "license": "MIT", - "engines": { - "node": ">=12.20.0" - } - }, "node_modules/parse5": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/parse5/-/parse5-5.1.1.tgz", diff --git a/package.json b/package.json index f30feb9..518e7c2 100644 --- a/package.json +++ b/package.json @@ -85,7 +85,7 @@ }, "devDependencies": { "@arethetypeswrong/cli": "0.18.5", - "@biomejs/biome": "2.5.15", + "@biomejs/biome": "2.6.4", "@d2t/vitest-ctrf-json-reporter": "1.3.0", "@types/node": "26.6.6", "@types/yargs": "17.0.35", diff --git a/src/README.md b/src/README.md index bb36c7e..6d5af5f 100644 --- a/src/README.md +++ b/src/README.md @@ -11,36 +11,36 @@ npm install ctrf ## Quick Start ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Build a report using the fluent API const report = new ctrf.ReportBuilder() - .tool({ name: 'jest', version: '29.0.0' }) - .addTest( - new ctrf.TestBuilder() - .name('should add numbers') - .status('passed') - .duration(150) - .build() - ) - .addTest( - new ctrf.TestBuilder() - .name('should handle errors') - .status('failed') - .duration(200) - .message('Expected 5 but got 4') - .build() - ) - .build() + .tool({ name: "jest", version: "29.0.0" }) + .addTest( + new ctrf.TestBuilder() + .name("should add numbers") + .status("passed") + .duration(150) + .build(), + ) + .addTest( + new ctrf.TestBuilder() + .name("should handle errors") + .status("failed") + .duration(200) + .message("Expected 5 but got 4") + .build(), + ) + .build(); // Validate the report -const result = ctrf.validateStrict(report) +const result = ctrf.validateStrict(report); if (!result.valid) { - console.error('Validation errors:', result.errors) + console.error("Validation errors:", result.errors); } // Write to file -await ctrf.writeReport(report, './ctrf-report.json') +await ctrf.writeReport(report, "./ctrf-report.json"); ``` ## API Reference @@ -49,226 +49,226 @@ await ctrf.writeReport(report, './ctrf-report.json') ### Core Types -| Type | Description | -|------|-------------| -| `CTRFReport` | The root report document containing results and metadata | -| `Results` | Test results including summary, tests, and optional environment | -| `Test` | Individual test case with status, duration, and metadata | -| `Summary` | Aggregated test counts and timing information | -| `Tool` | Information about the test framework/tool | -| `Environment` | Optional environment metadata (OS, browser, etc.) | +| Type | Description | +| ------------- | --------------------------------------------------------------- | +| `CTRFReport` | The root report document containing results and metadata | +| `Results` | Test results including summary, tests, and optional environment | +| `Test` | Individual test case with status, duration, and metadata | +| `Summary` | Aggregated test counts and timing information | +| `Tool` | Information about the test framework/tool | +| `Environment` | Optional environment metadata (OS, browser, etc.) | ### Validation ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Quick validation (returns boolean) if (ctrf.isValid(report)) { - console.log('Report is valid') + console.log("Report is valid"); } // Detailed validation (returns ValidationResult) -const result = ctrf.validate(report) +const result = ctrf.validate(report); if (!result.valid) { - result.errors?.forEach(err => console.error(err.message)) + result.errors?.forEach((err) => console.error(err.message)); } // Strict validation (throws on invalid) try { - ctrf.validateStrict(report) + ctrf.validateStrict(report); } catch (error) { - if (error instanceof ctrf.ValidationError) { - console.error('Invalid report:', error.errors) - } + if (error instanceof ctrf.ValidationError) { + console.error("Invalid report:", error.errors); + } } // Type guards if (ctrf.isCTRFReport(data)) { - // data is typed as CTRFReport + // data is typed as CTRFReport } ``` ### Building Reports ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // ReportBuilder - fluent API for constructing reports const report = new ctrf.ReportBuilder() - .tool({ name: 'vitest', version: '1.0.0' }) - .environment({ os: 'linux', arch: 'x64' }) - .addTest(/* ... */) - .build() + .tool({ name: "vitest", version: "1.0.0" }) + .environment({ os: "linux", arch: "x64" }) + .addTest(/* ... */) + .build(); // TestBuilder - fluent API for constructing tests const test = new ctrf.TestBuilder() - .name('User login test') - .status('passed') - .duration(1500) - .suite(['Authentication', 'Login']) - .tags(['smoke', 'critical']) - .filePath('tests/auth/login.test.ts') - .browser('chrome') - .build() + .name("User login test") + .status("passed") + .duration(1500) + .suite(["Authentication", "Login"]) + .tags(["smoke", "critical"]) + .filePath("tests/auth/login.test.ts") + .browser("chrome") + .build(); ``` ### Reading & Writing Reports ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Async file operations -const report = await ctrf.readReport('./ctrf-report.json') -await ctrf.writeReport(report, './output.json') +const report = await ctrf.readReport("./ctrf-report.json"); +await ctrf.writeReport(report, "./output.json"); // Sync file operations -const reportSync = ctrf.readReportSync('./ctrf-report.json') -ctrf.writeReportSync(report, './output.json') +const reportSync = ctrf.readReportSync("./ctrf-report.json"); +ctrf.writeReportSync(report, "./output.json"); // Parse from string -const parsed = ctrf.parse(jsonString) +const parsed = ctrf.parse(jsonString); // Stringify with formatting -const json = ctrf.stringify(report, { pretty: true, indent: 2 }) +const json = ctrf.stringify(report, { pretty: true, indent: 2 }); ``` ### Filtering & Querying ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Get tests by status -const failed = ctrf.getFailedTests(report) -const passed = ctrf.getPassedTests(report) -const skipped = ctrf.getSkippedTests(report) -const flaky = ctrf.getFlakyTests(report) +const failed = ctrf.getFailedTests(report); +const passed = ctrf.getPassedTests(report); +const skipped = ctrf.getSkippedTests(report); +const flaky = ctrf.getFlakyTests(report); // Filter by criteria const filtered = ctrf.filterTests(report, { - status: 'failed', - suite: 'Authentication', - tags: ['smoke'], -}) + status: "failed", + suite: "Authentication", + tags: ["smoke"], +}); // Find specific test -const test = ctrf.findTest(report, { name: 'login test' }) -const testById = ctrf.findTest(report, { id: 'test-uuid' }) +const test = ctrf.findTest(report, { name: "login test" }); +const testById = ctrf.findTest(report, { id: "test-uuid" }); // Group tests -const bySuite = ctrf.groupBy(report.results.tests, 'suite') -const byStatus = ctrf.groupBy(report.results.tests, 'status') +const bySuite = ctrf.groupBy(report.results.tests, "suite"); +const byStatus = ctrf.groupBy(report.results.tests, "status"); // Get unique values -const suites = ctrf.getUniqueSuites(report) -const tags = ctrf.getUniqueTags(report) +const suites = ctrf.getUniqueSuites(report); +const tags = ctrf.getUniqueTags(report); ``` ### Merging Reports ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Merge multiple reports into one const merged = ctrf.merge([report1, report2, report3], { - deduplicateTests: true, // Remove duplicate tests by ID -}) + deduplicateTests: true, // Remove duplicate tests by ID +}); ``` ### ID Generation ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Generate deterministic test ID from properties const testId = ctrf.generateTestId({ - name: 'should add numbers', - suite: ['Math', 'Addition'], - filePath: 'tests/math.test.ts', -}) + name: "should add numbers", + suite: ["Math", "Addition"], + filePath: "tests/math.test.ts", +}); // Generate random report ID -const reportId = ctrf.generateReportId() +const reportId = ctrf.generateReportId(); ``` ### Insights & Analytics ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Enrich a report with insights from historical data const enriched = ctrf.enrichReportWithInsights( - currentReport, - historicalReports, - { baseline: baselineReport } -) + currentReport, + historicalReports, + { baseline: baselineReport }, +); // Access insights -console.log(enriched.insights?.passRate) // { current: 0.95, baseline: 0.90, change: 0.05 } -console.log(enriched.insights?.flakyRate) // { current: 0.02, baseline: 0.05, change: -0.03 } +console.log(enriched.insights?.passRate); // { current: 0.95, baseline: 0.90, change: 0.05 } +console.log(enriched.insights?.flakyRate); // { current: 0.02, baseline: 0.05, change: -0.03 } // Calculate insights separately -const insights = ctrf.calculateInsights(reports, { window: 10 }) +const insights = ctrf.calculateInsights(reports, { window: 10 }); // Check if a test is flaky -const isFlaky = ctrf.isTestFlaky(test) +const isFlaky = ctrf.isTestFlaky(test); ``` ### Summary Calculation ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Calculate summary from tests -const summary = ctrf.calculateSummary(tests) +const summary = ctrf.calculateSummary(tests); // { tests: 10, passed: 8, failed: 1, skipped: 1, pending: 0, other: 0, ... } // Recalculate summary for existing report -const updated = ctrf.recalculateSummary(report) +const updated = ctrf.recalculateSummary(report); ``` ### Constants ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; -ctrf.REPORT_FORMAT // 'ctrf' -ctrf.CURRENT_SPEC_VERSION // '0.1.0' -ctrf.SUPPORTED_SPEC_VERSIONS // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0'] -ctrf.TEST_STATUSES // ['passed', 'failed', 'skipped', 'pending', 'other'] -ctrf.CTRF_NAMESPACE // UUID namespace for deterministic IDs +ctrf.REPORT_FORMAT; // 'ctrf' +ctrf.CURRENT_SPEC_VERSION; // '0.1.0' +ctrf.SUPPORTED_SPEC_VERSIONS; // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0'] +ctrf.TEST_STATUSES; // ['passed', 'failed', 'skipped', 'pending', 'other'] +ctrf.CTRF_NAMESPACE; // UUID namespace for deterministic IDs ``` ### Error Handling ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; try { - const report = await ctrf.readReport('./missing.json') + const report = await ctrf.readReport("./missing.json"); } catch (error) { - if (error instanceof ctrf.FileError) { - console.error('File not found:', error.path) - } else if (error instanceof ctrf.ParseError) { - console.error('Invalid JSON:', error.message) - } else if (error instanceof ctrf.ValidationError) { - console.error('Schema validation failed:', error.errors) - } + if (error instanceof ctrf.FileError) { + console.error("File not found:", error.path); + } else if (error instanceof ctrf.ParseError) { + console.error("Invalid JSON:", error.message); + } else if (error instanceof ctrf.ValidationError) { + console.error("Schema validation failed:", error.errors); + } } ``` ### Schema Access ```typescript -import { ctrf } from 'ctrf' +import { ctrf } from "ctrf"; // Get a historical schema or the latest published schema -const historicalSchema = ctrf.getSchema('0.0.2') -const latestSchema = ctrf.getSchema('latest') +const historicalSchema = ctrf.getSchema("0.0.2"); +const latestSchema = ctrf.getSchema("latest"); // Get version info -const version = ctrf.getCurrentSpecVersion() // '0.1.0' -const supported = ctrf.getSupportedSpecVersions() // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0'] +const version = ctrf.getCurrentSpecVersion(); // '0.1.0' +const supported = ctrf.getSupportedSpecVersions(); // ['0.0.1', '0.0.2', '0.0.3', '0.0.4', '0.1.0'] ``` ## Design Principles diff --git a/website/reference.md b/website/reference.md index c7bf7b0..3d7631a 100644 --- a/website/reference.md +++ b/website/reference.md @@ -1,4 +1,5 @@ --- + title: TypeScript Reference sidebar_label: TypeScript Reference description: Complete API reference for the CTRF TypeScript reference implementation @@ -18,34 +19,34 @@ npm install ctrf ```typescript import { - validate, - parse, - ReportBuilder, - TestBuilder, - filterTests, - merge, -} from 'ctrf' + validate, + parse, + ReportBuilder, + TestBuilder, + filterTests, + merge, +} from "ctrf"; // Validate a report -const result = validate(report) +const result = validate(report); if (result.valid) { - console.log('Report is valid!') + console.log("Report is valid!"); } // Parse JSON -const report = parse(jsonString, { validate: true }) +const report = parse(jsonString, { validate: true }); // Build reports programmatically const report = new ReportBuilder() - .tool({ name: 'jest', version: '29.0.0' }) - .addTest( - new TestBuilder() - .name('should add numbers') - .status('passed') - .duration(150) - .build() - ) - .build() + .tool({ name: "jest", version: "29.0.0" }) + .addTest( + new TestBuilder() + .name("should add numbers") + .status("passed") + .duration(150) + .build(), + ) + .build(); ``` --- @@ -57,7 +58,7 @@ const report = new ReportBuilder() Validate a CTRF report against the JSON schema. ```typescript -function validate(report: unknown, options?: ValidateOptions): ValidationResult +function validate(report: unknown, options?: ValidateOptions): ValidationResult; ``` **Parameters:** @@ -70,15 +71,15 @@ function validate(report: unknown, options?: ValidateOptions): ValidationResult **Example:** ```typescript -import { validate } from 'ctrf' +import { validate } from "ctrf"; -const result = validate(report) +const result = validate(report); if (!result.valid) { - console.log('Validation errors:', result.errors) + console.log("Validation errors:", result.errors); } // Validate against specific version -const result = validate(report, { specVersion: '0.0.0' }) +const result = validate(report, { specVersion: "0.0.0" }); ``` ### isValid @@ -86,17 +87,17 @@ const result = validate(report, { specVersion: '0.0.0' }) Type guard to check if a report is valid. ```typescript -function isValid(report: unknown): report is CTRFReport +function isValid(report: unknown): report is CTRFReport; ``` **Example:** ```typescript -import { isValid } from 'ctrf' +import { isValid } from "ctrf"; if (isValid(report)) { - // TypeScript knows report is CTRFReport - console.log(report.results.summary.passed) + // TypeScript knows report is CTRFReport + console.log(report.results.summary.passed); } ``` @@ -105,7 +106,7 @@ if (isValid(report)) { Validate and throw if invalid. ```typescript -function validateStrict(report: unknown): asserts report is CTRFReport +function validateStrict(report: unknown): asserts report is CTRFReport; ``` **Throws:** `ValidationError` if the report is invalid @@ -113,15 +114,15 @@ function validateStrict(report: unknown): asserts report is CTRFReport **Example:** ```typescript -import { validateStrict, ValidationError } from 'ctrf' +import { validateStrict, ValidationError } from "ctrf"; try { - validateStrict(report) - // TypeScript knows report is CTRFReport + validateStrict(report); + // TypeScript knows report is CTRFReport } catch (e) { - if (e instanceof ValidationError) { - console.log(e.errors) - } + if (e instanceof ValidationError) { + console.log(e.errors); + } } ``` @@ -130,7 +131,7 @@ try { Parse a JSON string into a CTRFReport. ```typescript -function parse(json: string, options?: ParseOptions): CTRFReport +function parse(json: string, options?: ParseOptions): CTRFReport; ``` **Parameters:** @@ -143,12 +144,12 @@ function parse(json: string, options?: ParseOptions): CTRFReport **Example:** ```typescript -import { parse } from 'ctrf' +import { parse } from "ctrf"; -const report = parse(jsonString) +const report = parse(jsonString); // With validation -const report = parse(jsonString, { validate: true }) +const report = parse(jsonString, { validate: true }); ``` ### stringify @@ -156,7 +157,7 @@ const report = parse(jsonString, { validate: true }) Serialize a CTRFReport to JSON. ```typescript -function stringify(report: CTRFReport, options?: StringifyOptions): string +function stringify(report: CTRFReport, options?: StringifyOptions): string; ``` **Parameters:** @@ -168,15 +169,15 @@ function stringify(report: CTRFReport, options?: StringifyOptions): string **Example:** ```typescript -import { stringify } from 'ctrf' +import { stringify } from "ctrf"; -const json = stringify(report) +const json = stringify(report); // Pretty print -const json = stringify(report, { pretty: true }) +const json = stringify(report, { pretty: true }); // Custom indent -const json = stringify(report, { pretty: true, indent: 4 }) +const json = stringify(report, { pretty: true, indent: 4 }); ``` ### calculateSummary @@ -184,7 +185,7 @@ const json = stringify(report, { pretty: true, indent: 4 }) Calculate summary statistics from an array of tests. ```typescript -function calculateSummary(tests: Test[], options?: SummaryOptions): Summary +function calculateSummary(tests: Test[], options?: SummaryOptions): Summary; ``` **Parameters:** @@ -196,15 +197,15 @@ function calculateSummary(tests: Test[], options?: SummaryOptions): Summary **Example:** ```typescript -import { calculateSummary } from 'ctrf' +import { calculateSummary } from "ctrf"; -const summary = calculateSummary(tests) +const summary = calculateSummary(tests); // With timing overrides const summary = calculateSummary(tests, { - start: 1704067200000, - stop: 1704067260000, -}) + start: 1704067200000, + stop: 1704067260000, +}); ``` --- @@ -217,21 +218,21 @@ Fluent builder for constructing CTRF reports. ```typescript class ReportBuilder { - constructor(options?: ReportBuilderOptions) - - specVersion(version: string): this - reportId(uuid?: string): this - timestamp(date?: Date | string): this - generatedBy(name: string): this - tool(tool: Tool): this - environment(env: Environment): this - addTest(test: Test): this - addTests(tests: Test[]): this - insights(insights: Insights): this - baseline(baseline: Baseline): this - extra(data: Record): this - summaryOverrides(overrides: Partial): this - build(): CTRFReport + constructor(options?: ReportBuilderOptions); + + specVersion(version: string): this; + reportId(uuid?: string): this; + timestamp(date?: Date | string): this; + generatedBy(name: string): this; + tool(tool: Tool): this; + environment(env: Environment): this; + addTest(test: Test): this; + addTests(tests: Test[]): this; + insights(insights: Insights): this; + baseline(baseline: Baseline): this; + extra(data: Record): this; + summaryOverrides(overrides: Partial): this; + build(): CTRFReport; } ``` @@ -243,28 +244,28 @@ class ReportBuilder { **Example:** ```typescript -import { ReportBuilder, TestBuilder } from 'ctrf' +import { ReportBuilder, TestBuilder } from "ctrf"; const report = new ReportBuilder({ autoGenerateId: true, autoTimestamp: true }) - .specVersion('0.0.0') - .tool({ name: 'jest', version: '29.0.0' }) - .environment({ branchName: 'main', commit: 'abc123' }) - .addTest( - new TestBuilder() - .name('should add numbers') - .status('passed') - .duration(150) - .build() - ) - .addTest( - new TestBuilder() - .name('should handle errors') - .status('failed') - .duration(200) - .message('Expected 5 but got 4') - .build() - ) - .build() + .specVersion("0.0.0") + .tool({ name: "jest", version: "29.0.0" }) + .environment({ branchName: "main", commit: "abc123" }) + .addTest( + new TestBuilder() + .name("should add numbers") + .status("passed") + .duration(150) + .build(), + ) + .addTest( + new TestBuilder() + .name("should handle errors") + .status("failed") + .duration(200) + .message("Expected 5 but got 4") + .build(), + ) + .build(); ``` ### TestBuilder @@ -273,38 +274,38 @@ Fluent builder for constructing Test objects. ```typescript class TestBuilder { - constructor(options?: TestBuilderOptions) - - id(uuid?: string): this - name(name: string): this - status(status: TestStatus): this - duration(ms: number): this - start(timestamp: number): this - stop(timestamp: number): this - suite(suite: string[]): this - message(message: string): this - trace(trace: string): this - snippet(snippet: string): this - ai(ai: string): this - line(line: number): this - rawStatus(rawStatus: string): this - tags(tags: string[]): this - type(type: string): this - filePath(filePath: string): this - retries(retries: number): this - addRetryAttempt(attempt: RetryAttempt): this - flaky(flaky: boolean): this - stdout(stdout: string[]): this - stderr(stderr: string[]): this - threadId(threadId: string): this - browser(browser: string): this - device(device: string): this - screenshot(screenshot: string): this - parameters(params: Record): this - addStep(step: Step): this - addAttachment(attachment: Attachment): this - extra(data: Record): this - build(): Test + constructor(options?: TestBuilderOptions); + + id(uuid?: string): this; + name(name: string): this; + status(status: TestStatus): this; + duration(ms: number): this; + start(timestamp: number): this; + stop(timestamp: number): this; + suite(suite: string[]): this; + message(message: string): this; + trace(trace: string): this; + snippet(snippet: string): this; + ai(ai: string): this; + line(line: number): this; + rawStatus(rawStatus: string): this; + tags(tags: string[]): this; + type(type: string): this; + filePath(filePath: string): this; + retries(retries: number): this; + addRetryAttempt(attempt: RetryAttempt): this; + flaky(flaky: boolean): this; + stdout(stdout: string[]): this; + stderr(stderr: string[]): this; + threadId(threadId: string): this; + browser(browser: string): this; + device(device: string): this; + screenshot(screenshot: string): this; + parameters(params: Record): this; + addStep(step: Step): this; + addAttachment(attachment: Attachment): this; + extra(data: Record): this; + build(): Test; } ``` @@ -315,17 +316,17 @@ class TestBuilder { **Example:** ```typescript -import { TestBuilder } from 'ctrf' +import { TestBuilder } from "ctrf"; const test = new TestBuilder({ autoGenerateId: true }) - .name('should validate user input') - .suite(['Authentication', 'Login']) - .status('passed') - .duration(245) - .filePath('tests/auth/login.test.ts') - .tags(['smoke', 'auth']) - .type('integration') - .build() + .name("should validate user input") + .suite(["Authentication", "Login"]) + .status("passed") + .duration(245) + .filePath("tests/auth/login.test.ts") + .tags(["smoke", "auth"]) + .type("integration") + .build(); ``` --- @@ -337,7 +338,7 @@ const test = new TestBuilder({ autoGenerateId: true }) Filter tests in a report by criteria. ```typescript -function filterTests(report: CTRFReport, criteria: FilterCriteria): Test[] +function filterTests(report: CTRFReport, criteria: FilterCriteria): Test[]; ``` **FilterCriteria:** @@ -352,22 +353,22 @@ function filterTests(report: CTRFReport, criteria: FilterCriteria): Test[] **Example:** ```typescript -import { filterTests } from 'ctrf' +import { filterTests } from "ctrf"; // Filter by status -const failed = filterTests(report, { status: 'failed' }) +const failed = filterTests(report, { status: "failed" }); // Multiple statuses const notPassed = filterTests(report, { - status: ['failed', 'skipped'], -}) + status: ["failed", "skipped"], +}); // Multiple criteria const filtered = filterTests(report, { - status: 'failed', - tags: ['smoke'], - flaky: true, -}) + status: "failed", + tags: ["smoke"], + flaky: true, +}); ``` ### findTest @@ -376,9 +377,9 @@ Find a single test in a report. ```typescript function findTest( - report: CTRFReport, - criteria: FilterCriteria -): Test | undefined + report: CTRFReport, + criteria: FilterCriteria, +): Test | undefined; ``` **Additional FilterCriteria for findTest:** @@ -389,16 +390,16 @@ function findTest( **Example:** ```typescript -import { findTest } from 'ctrf' +import { findTest } from "ctrf"; // Find by ID -const test = findTest(report, { id: 'test-uuid' }) +const test = findTest(report, { id: "test-uuid" }); // Find by name -const test = findTest(report, { name: 'should login successfully' }) +const test = findTest(report, { name: "should login successfully" }); // Find by criteria -const test = findTest(report, { status: 'failed', flaky: true }) +const test = findTest(report, { status: "failed", flaky: true }); ``` --- @@ -410,7 +411,7 @@ const test = findTest(report, { status: 'failed', flaky: true }) Merge multiple CTRF reports into a single report. ```typescript -function merge(reports: CTRFReport[], options?: MergeOptions): CTRFReport +function merge(reports: CTRFReport[], options?: MergeOptions): CTRFReport; ``` **MergeOptions:** @@ -422,20 +423,20 @@ function merge(reports: CTRFReport[], options?: MergeOptions): CTRFReport **Example:** ```typescript -import { merge } from 'ctrf' +import { merge } from "ctrf"; // Basic merge -const merged = merge([report1, report2, report3]) +const merged = merge([report1, report2, report3]); // With deduplication const merged = merge(reports, { - deduplicateTests: true, -}) + deduplicateTests: true, +}); // Keep first environment only const merged = merge(reports, { - preserveEnvironment: 'first', -}) + preserveEnvironment: "first", +}); ``` --- @@ -448,10 +449,10 @@ Add historical insights to a report by analyzing previous reports. ```typescript function addInsights( - report: CTRFReport, - historicalReports?: CTRFReport[], - options?: InsightsOptions -): CTRFReport + report: CTRFReport, + historicalReports?: CTRFReport[], + options?: InsightsOptions, +): CTRFReport; ``` **InsightsOptions:** @@ -461,15 +462,15 @@ function addInsights( **Example:** ```typescript -import { addInsights } from 'ctrf' +import { addInsights } from "ctrf"; // Add insights from historical data -const reportWithInsights = addInsights(currentReport, previousReports) +const reportWithInsights = addInsights(currentReport, previousReports); // With baseline comparison const reportWithInsights = addInsights(currentReport, previousReports, { - baseline: baselineReport, -}) + baseline: baselineReport, +}); ``` ### isTestFlaky @@ -477,7 +478,7 @@ const reportWithInsights = addInsights(currentReport, previousReports, { Determine if a test is flaky based on CTRF specification. ```typescript -function isTestFlaky(test: Test): boolean +function isTestFlaky(test: Test): boolean; ``` A test is flaky if: @@ -488,10 +489,10 @@ A test is flaky if: **Example:** ```typescript -import { isTestFlaky } from 'ctrf' +import { isTestFlaky } from "ctrf"; if (isTestFlaky(test)) { - console.log('Test is flaky:', test.name) + console.log("Test is flaky:", test.name); } ``` @@ -505,10 +506,10 @@ Generate a deterministic UUID v5 for a test based on its properties. ```typescript function generateTestId(properties: { - name: string - suite?: string[] - filePath?: string -}): string + name: string; + suite?: string[]; + filePath?: string; +}): string; ``` The same inputs always produce the same UUID, enabling cross-run analysis. @@ -516,13 +517,13 @@ The same inputs always produce the same UUID, enabling cross-run analysis. **Example:** ```typescript -import { generateTestId } from 'ctrf' +import { generateTestId } from "ctrf"; const id = generateTestId({ - name: 'should add numbers', - suite: ['math', 'addition'], - filePath: 'tests/math.test.ts', -}) + name: "should add numbers", + suite: ["math", "addition"], + filePath: "tests/math.test.ts", +}); // Always returns the same UUID for these inputs ``` @@ -531,15 +532,15 @@ const id = generateTestId({ Generate a random UUID v4 for report identification. ```typescript -function generateReportId(): string +function generateReportId(): string; ``` **Example:** ```typescript -import { generateReportId } from 'ctrf' +import { generateReportId } from "ctrf"; -const reportId = generateReportId() +const reportId = generateReportId(); // => 'f47ac10b-58cc-4372-a567-0e02b2c3d479' ``` @@ -552,7 +553,7 @@ const reportId = generateReportId() Get the JSON Schema for a specific CTRF spec version. ```typescript -function getSchema(version: string): object +function getSchema(version: string): object; ``` **Throws:** `SchemaVersionError` if version is not supported @@ -560,9 +561,9 @@ function getSchema(version: string): object **Example:** ```typescript -import { getSchema } from 'ctrf' +import { getSchema } from "ctrf"; -const schema = getSchema('0.0.0') +const schema = getSchema("0.0.0"); ``` ### getCurrentSpecVersion @@ -570,7 +571,7 @@ const schema = getSchema('0.0.0') Get the current spec version. ```typescript -function getCurrentSpecVersion(): string +function getCurrentSpecVersion(): string; ``` ### getSupportedSpecVersions @@ -578,7 +579,7 @@ function getCurrentSpecVersion(): string Get all supported spec versions. ```typescript -function getSupportedSpecVersions(): readonly string[] +function getSupportedSpecVersions(): readonly string[]; ``` ### schema @@ -586,8 +587,8 @@ function getSupportedSpecVersions(): readonly string[] The current version CTRF JSON Schema object. ```typescript -import { schema } from 'ctrf' -console.log(schema.$schema) +import { schema } from "ctrf"; +console.log(schema.$schema); ``` --- @@ -601,16 +602,16 @@ Runtime type checking functions. Quick check if an object has CTRF report structure. ```typescript -function isCTRFReport(report: unknown): report is { reportFormat: 'CTRF' } +function isCTRFReport(report: unknown): report is { reportFormat: "CTRF" }; ``` **Example:** ```typescript -import { isCTRFReport } from 'ctrf' +import { isCTRFReport } from "ctrf"; if (isCTRFReport(data)) { - // data.reportFormat is 'CTRF' + // data.reportFormat is 'CTRF' } ``` @@ -619,7 +620,7 @@ if (isCTRFReport(data)) { Type guard for Test objects. ```typescript -function isTest(test: unknown): test is Test +function isTest(test: unknown): test is Test; ``` ### isTestStatus @@ -627,7 +628,7 @@ function isTest(test: unknown): test is Test Type guard for valid test statuses. ```typescript -function isTestStatus(status: unknown): status is TestStatus +function isTestStatus(status: unknown): status is TestStatus; ``` ### isRetryAttempt @@ -635,7 +636,7 @@ function isTestStatus(status: unknown): status is TestStatus Type guard for RetryAttempt objects. ```typescript -function isRetryAttempt(attempt: unknown): attempt is RetryAttempt +function isRetryAttempt(attempt: unknown): attempt is RetryAttempt; ``` ### hasInsights @@ -643,7 +644,7 @@ function isRetryAttempt(attempt: unknown): attempt is RetryAttempt Check if a report has insights data. ```typescript -function hasInsights(report: CTRFReport): boolean +function hasInsights(report: CTRFReport): boolean; ``` --- @@ -652,12 +653,12 @@ function hasInsights(report: CTRFReport): boolean ```typescript import { - REPORT_FORMAT, // 'CTRF' - CURRENT_SPEC_VERSION, // '0.0.0' - TEST_STATUSES, // ['passed', 'failed', 'skipped', 'pending', 'other'] - SUPPORTED_SPEC_VERSIONS, // ['0.0.0'] - CTRF_NAMESPACE, // UUID namespace for deterministic IDs -} from 'ctrf' + REPORT_FORMAT, // 'CTRF' + CURRENT_SPEC_VERSION, // '0.0.0' + TEST_STATUSES, // ['passed', 'failed', 'skipped', 'pending', 'other'] + SUPPORTED_SPEC_VERSIONS, // ['0.0.0'] + CTRF_NAMESPACE, // UUID namespace for deterministic IDs +} from "ctrf"; ``` --- @@ -672,7 +673,7 @@ Base error class for all CTRF errors. ```typescript class CTRFError extends Error { - name: 'CTRFError' + name: "CTRFError"; } ``` @@ -682,13 +683,13 @@ Thrown when schema validation fails. ```typescript class ValidationError extends CTRFError { - errors: ValidationErrorDetail[] + errors: ValidationErrorDetail[]; } interface ValidationErrorDetail { - message: string - path: string - keyword?: string + message: string; + path: string; + keyword?: string; } ``` @@ -698,7 +699,7 @@ Thrown when JSON parsing fails. ```typescript class ParseError extends CTRFError { - cause?: Error + cause?: Error; } ``` @@ -708,8 +709,8 @@ Thrown when an unsupported spec version is encountered. ```typescript class SchemaVersionError extends CTRFError { - version: string - supportedVersions: string[] + version: string; + supportedVersions: string[]; } ``` @@ -719,8 +720,8 @@ Thrown when file operations fail. ```typescript class FileError extends CTRFError { - filePath: string - cause?: Error + filePath: string; + cause?: Error; } ``` @@ -744,15 +745,15 @@ The root report object. ```typescript interface CTRFReport { - reportFormat: 'CTRF' - specVersion: string - reportId?: string - timestamp?: string - generatedBy?: string - results: Results - insights?: Insights - baseline?: Baseline - extra?: Record + reportFormat: "CTRF"; + specVersion: string; + reportId?: string; + timestamp?: string; + generatedBy?: string; + results: Results; + insights?: Insights; + baseline?: Baseline; + extra?: Record; } ``` @@ -762,35 +763,35 @@ Individual test result. ```typescript interface Test { - id?: string - name: string - status: TestStatus - duration: number - start?: number - stop?: number - suite?: string[] - message?: string - trace?: string - snippet?: string - ai?: string - line?: number - rawStatus?: string - tags?: string[] - type?: string - filePath?: string - retries?: number - retryAttempts?: RetryAttempt[] - flaky?: boolean - stdout?: string[] - stderr?: string[] - threadId?: string - browser?: string - device?: string - screenshot?: string - parameters?: Record - steps?: Step[] - attachments?: Attachment[] - extra?: Record + id?: string; + name: string; + status: TestStatus; + duration: number; + start?: number; + stop?: number; + suite?: string[]; + message?: string; + trace?: string; + snippet?: string; + ai?: string; + line?: number; + rawStatus?: string; + tags?: string[]; + type?: string; + filePath?: string; + retries?: number; + retryAttempts?: RetryAttempt[]; + flaky?: boolean; + stdout?: string[]; + stderr?: string[]; + threadId?: string; + browser?: string; + device?: string; + screenshot?: string; + parameters?: Record; + steps?: Step[]; + attachments?: Attachment[]; + extra?: Record; } ``` @@ -800,11 +801,11 @@ Container for test results. ```typescript interface Results { - tool: Tool - summary: Summary - tests: Test[] - environment?: Environment - extra?: Record + tool: Tool; + summary: Summary; + tests: Test[]; + environment?: Environment; + extra?: Record; } ``` @@ -814,18 +815,18 @@ Aggregated test statistics. ```typescript interface Summary { - tests: number - passed: number - failed: number - skipped: number - pending: number - other: number - flaky?: number - suites?: number - start: number - stop: number - duration?: number - extra?: Record + tests: number; + passed: number; + failed: number; + skipped: number; + pending: number; + other: number; + flaky?: number; + suites?: number; + start: number; + stop: number; + duration?: number; + extra?: Record; } ``` @@ -835,9 +836,9 @@ Test tool information. ```typescript interface Tool { - name: string - version?: string - extra?: Record + name: string; + version?: string; + extra?: Record; } ``` @@ -847,20 +848,20 @@ Environment metadata. ```typescript interface Environment { - appName?: string - appVersion?: string - buildName?: string - buildNumber?: string - buildUrl?: string - repositoryName?: string - repositoryUrl?: string - commit?: string - branchName?: string - osPlatform?: string - osRelease?: string - osVersion?: string - testEnvironment?: string - extra?: Record + appName?: string; + appVersion?: string; + buildName?: string; + buildNumber?: string; + buildUrl?: string; + repositoryName?: string; + repositoryUrl?: string; + commit?: string; + branchName?: string; + osPlatform?: string; + osRelease?: string; + osVersion?: string; + testEnvironment?: string; + extra?: Record; } ``` @@ -869,61 +870,61 @@ interface Environment { Valid test status values. ```typescript -type TestStatus = 'passed' | 'failed' | 'skipped' | 'pending' | 'other' +type TestStatus = "passed" | "failed" | "skipped" | "pending" | "other"; ``` ### Supporting Types ```typescript interface Attachment { - name: string - path?: string - contentType?: string - content?: string + name: string; + path?: string; + contentType?: string; + content?: string; } interface Step { - name: string - status: TestStatus - duration?: number - start?: number - stop?: number - message?: string + name: string; + status: TestStatus; + duration?: number; + start?: number; + stop?: number; + message?: string; } interface RetryAttempt { - attempt: number - status: TestStatus - duration?: number - message?: string - trace?: string + attempt: number; + status: TestStatus; + duration?: number; + message?: string; + trace?: string; } interface Insights { - flakiness?: MetricDelta - failRate?: MetricDelta - newFailures?: number - extra?: Record + flakiness?: MetricDelta; + failRate?: MetricDelta; + newFailures?: number; + extra?: Record; } interface TestInsights { - flakiness?: MetricDelta - failRate?: MetricDelta - averageDuration?: MetricDelta - p95Duration?: MetricDelta - extra?: Record + flakiness?: MetricDelta; + failRate?: MetricDelta; + averageDuration?: MetricDelta; + p95Duration?: MetricDelta; + extra?: Record; } interface MetricDelta { - current?: number - baseline?: number - change?: number + current?: number; + baseline?: number; + change?: number; } interface Baseline { - reportId?: string - timestamp?: string - summary?: Summary + reportId?: string; + timestamp?: string; + summary?: Summary; } ``` @@ -933,64 +934,64 @@ interface Baseline { ```typescript import { - ReportBuilder, - TestBuilder, - validate, - stringify, - filterTests, - addInsights, - merge, - type CTRFReport, - type Test, -} from 'ctrf' + ReportBuilder, + TestBuilder, + validate, + stringify, + filterTests, + addInsights, + merge, + type CTRFReport, + type Test, +} from "ctrf"; // Build a report const report = new ReportBuilder({ autoGenerateId: true, autoTimestamp: true }) - .tool({ name: 'vitest', version: '1.0.0' }) - .environment({ - branchName: 'main', - commit: 'abc123', - buildNumber: '42', - }) - .addTest( - new TestBuilder({ autoGenerateId: true }) - .name('should create user') - .suite(['API', 'Users']) - .status('passed') - .duration(120) - .filePath('tests/api/users.test.ts') - .tags(['api', 'smoke']) - .build() - ) - .addTest( - new TestBuilder({ autoGenerateId: true }) - .name('should delete user') - .suite(['API', 'Users']) - .status('failed') - .duration(85) - .message('User not found') - .trace('Error: User not found\n at deleteUser (users.ts:42)') - .filePath('tests/api/users.test.ts') - .build() - ) - .build() + .tool({ name: "vitest", version: "1.0.0" }) + .environment({ + branchName: "main", + commit: "abc123", + buildNumber: "42", + }) + .addTest( + new TestBuilder({ autoGenerateId: true }) + .name("should create user") + .suite(["API", "Users"]) + .status("passed") + .duration(120) + .filePath("tests/api/users.test.ts") + .tags(["api", "smoke"]) + .build(), + ) + .addTest( + new TestBuilder({ autoGenerateId: true }) + .name("should delete user") + .suite(["API", "Users"]) + .status("failed") + .duration(85) + .message("User not found") + .trace("Error: User not found\n at deleteUser (users.ts:42)") + .filePath("tests/api/users.test.ts") + .build(), + ) + .build(); // Validate -const result = validate(report) -console.log('Valid:', result.valid) +const result = validate(report); +console.log("Valid:", result.valid); // Filter failed tests -const failed = filterTests(report, { status: 'failed' }) -console.log('Failed tests:', failed.length) +const failed = filterTests(report, { status: "failed" }); +console.log("Failed tests:", failed.length); // Serialize -const json = stringify(report, { pretty: true }) +const json = stringify(report, { pretty: true }); // Add insights from history -const reportWithInsights = addInsights(report, previousReports) +const reportWithInsights = addInsights(report, previousReports); // Merge parallel runs const merged = merge([shard1, shard2, shard3], { - deduplicateTests: true, -}) + deduplicateTests: true, +}); ```