Handlebars Helpers CTRF

A collection of Handlebars helpers for working with Common Test Report Format.

Installation

``bash
npm install handlebars-helpers-ctrf
`

Usage

`javascript
import Handlebars from 'handlebars'
import { loadHelpers } from 'handlebars-helpers-ctrf';

// Register all helpers with Handlebars
loadHelpers(Handlebars);


// Now you can use the helpers in your templates
const template = Handlebars.compile('{{append "test" ".html"}}');
const result = template({}); // "test.html"
`

Development

Contributions are very welcome! Please see the CONTRIBUTING.md file for more information.

To build the project and run the tests:

`bash
npm run all
`

Available Helpers

- Ctrf Helpers
- Array Helpers
- Collections Helpers
- Comparison Helpers
- Date Helpers
- Fs Helpers
- Inflection Helpers
- Match Helpers
- Math Helpers
- Misc Helpers
- Number Helpers
- Object Helpers
- Path Helpers
- Regex Helpers
- String Helpers
- Url Helpers

$3

#### sortTestsByFailRate

Sorts tests by their failure rate in descending order, showing the most unreliable tests first.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: Test[] - A sorted array of tests that have a fail rate, from highest to lowest.

Example:

`handlebars
Most Unreliable Tests:
{{#each (sortTestsByFailRate tests)}}
{{this.name}} - Fail Rate: {{this.insights.failRate.current}}%
{{/each}}
`

---

#### sortTestsByFlakyRate

Sorts tests by their flaky rate in descending order, showing the most flaky tests first.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: Test[] - A sorted array of tests that have a flaky rate, from highest to lowest.

Example:

`handlebars
Most Flaky Tests:
{{#each (sortTestsByFlakyRate tests)}}
{{this.name}} - Flaky Rate: {{this.insights.flakyRate.current}}%
{{/each}}
`

---

#### filterPassedTests

Filters test results to only include passed tests. Useful for creating success summaries or filtering out failures.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: Test[] - An array of tests with "passed" status.

Example:

`handlebars
Passed Tests:
{{#each (filterPassedTests tests)}}
✓ {{this.name}} ({{formatDuration this.duration}})
{{/each}}
`

---

#### filterFailedTests

Filters test results to only include failed tests. Useful for creating failure summaries or error reports.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: Test[] - An array of tests with "failed" status.

Example:

`handlebars
Failed Tests:
{{#each (filterFailedTests tests)}}
⊝ {{this.name}} ({{this.message}})
{{/each}}
`

---

#### filterOtherTests

Filters test results to only include tests with non-standard statuses (skipped, pending, other). Useful for creating comprehensive test summaries.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: Test[] - An array of tests with non-standard statuses.

Example:

`handlebars
Other Status Tests:
{{#each (filterOtherTests tests)}}
⊝ {{this.name}} ({{this.status}})
{{/each}}
`

---

#### countFlakyTests

Counts the total number of flaky tests in the test results.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: number - The total number of flaky tests.

Example:

`handlebars
Flaky tests detected: {{countFlakyTests tests}}
{{#if (countFlakyTests tests)}}⚠️{{/if}}
`

---

#### anyFlakyTests

Determines if there are any flaky tests in the test results. Useful for conditional rendering of flaky test warnings.

Parameters:

- tests (unknown) - An array of Test objects from CTRF report.

Returns: boolean - True if any test is marked as flaky, false otherwise.

Example:

`handlebars
{{#if (anyFlakyTests tests)}}
⚠️ Some tests are flaky and may need attention
{{else}}
✓ No flaky tests detected
{{/if}}
`

---

#### formatDurationFromTimes

Formats test execution duration from start and stop timestamps into a human-readable format. Handles edge cases where timing data might be missing or invalid.

Parameters:

- start (unknown) - The test start time in milliseconds.
- stop (unknown) - The test stop time in milliseconds.

Returns: string - A formatted duration string like "1ms", "1.2s", or "1m 30s".

Example:

`handlebars
Test Duration: {{formatDurationFromTimes test.start test.stop}}

`

---

#### formatDuration

Formats a test duration value in milliseconds into a human-readable format. Perfect for displaying test execution times in reports.

Parameters:

- duration (unknown) - The test duration in milliseconds.

Returns: string - A formatted duration string like "1ms", "1.2s", or "1m 30s".

Example:

`handlebars
{{test.name}} completed in {{formatDuration test.duration}}

`

---

#### formatTestMessage

Converts ANSI-formatted test messages into HTML and replaces newlines with
tags. Specifically designed for formatting the test.message property in CTRF reports. Ideal for rendering multi-line console messages with colors in a human-friendly HTML format. This helper formats test messages so they behave well with markdown and regular HTML content.

Parameters:

- text (string) - The test message to format, possibly containing ANSI codes and newlines.

Returns: string - An HTML-formatted string with ANSI codes converted to HTML and line breaks replaced.

Example:

`handlebars
{{formatTestMessage test.message}}
Returns: HTML with ANSI colors converted to spans and line breaks as
tags
{{#if test.message}}



{{/if}}
`

---

#### formatTestMessagePreCode

Similar to formatTestMessage, but designed to preserve code formatting more closely. Converts ANSI to HTML and reduces consecutive newlines, but does not replace them with
tags. Perfect for formatting code blocks, stack traces, and other pre-formatted content in test messages. This helper is specifically designed to be used in pre code blocks where newlines need to be preserved.

Parameters:

- text (unknown) - The test message to format, possibly containing ANSI codes.

Returns: string - An HTML-formatted string with ANSI codes converted to HTML and consecutive newlines minimized.

Example:

`handlebars


{{#if message}}{{formatTestMessagePreCode message}}{{else}}No message available{{/if}}


{{formatTestMessagePreCode test.message}}
Returns: HTML with ANSI colors converted but newlines preserved for

 blocks
{{#if test.message}}
{{{formatTestMessagePreCode test.message}}}

{{/if}}
`
---
#### limitFailedTests
Filters an array of tests to only those that have failed, then limits the result to a specified number. Perfect for displaying "Top N failed tests" in dashboards and summary reports.
Parameters:
- tests (unknown) - An array of Test objects from CTRF report.
- limit (unknown) - The maximum number of failed tests to return.
Returns: Test[] - An array of failed tests up to the specified limit.
Example:
`handlebars
{{#each (limitFailedTests tests 5)}}
{{this.name}}

{{/each}}

{{#each (limitFailedTests suite.tests 3)}}
{{this.name}} - {{this.status}}
{{/each}}

`
---
#### getCtrfEmoji
Retrieves an emoji representation for a given test state or category. Useful for adding visual flair to CTRF test reports, dashboards, and summaries.
Parameters:
- status (unknown) - The test state or category to get an emoji for.
Returns: string - The emoji corresponding to the test state or category.
Example:
`handlebars
{{getCtrfEmoji "passed"}}

{{getCtrfEmoji "failed"}}

{{getCtrfEmoji "flaky"}}

{{getCtrfEmoji "build"}}

Use with CTRF templates: Perfect for creating visually appealing test summaries, status indicators, and dashboard elements that make test reports more engaging and easier to scan.
`
---
$3
#### after
Returns all of the items in an array after the specified index. Opposite of before. Useful for slicing test result arrays to show only later results in CTRF reports.
Parameters:
- array (unknown) - The array from test data.
- n (unknown) - Starting index (number of items to exclude).
Returns: unknown[] - Array excluding n items from the start.
Example:
`handlebars
{{after test.results 1}}


`
---
#### arrayify
Cast the given value to an array. Useful for normalizing test data fields to arrays for consistent rendering in test reports.
Parameters:
- value (unknown) - The value to cast.
Returns: unknown[] - The value as an array.
Example:
`handlebars
{{arrayify test.status}}


`
---
#### before
Return all of the items in the collection before the specified count. Opposite of after. Useful for showing only the first N test results or errors in a summary table.
Parameters:
- array (unknown) - The array from test data.
- n (unknown) - Number of items to include from the start.
Returns: unknown[] - Array excluding items after the given number.
Example:
`handlebars
{{before test.results 2}}


`
---
#### eachIndex
Iterates over each item in an array and exposes the current item and index to the block. Useful for rendering test steps or log entries with their index in CTRF reports.
Parameters:
- array (unknown) - The array from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each item with index.
Example:
`handlebars
{{#eachIndex test.results}}
{{item}} is {{index}}
{{/eachIndex}}


`
---
#### filter
Block helper that filters the given array and renders the block for values that evaluate to true, otherwise the inverse block is returned. Useful for displaying only passing or failing tests in a filtered test report section.
Parameters:
- array (unknown) - The array from test data.
- value (unknown) - The value to filter by.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for filtered items.
Example:
`handlebars
{{#filter test.results "passed"}}AAA{{else}}BBB{{/filter}}


`
---
#### first
Returns the first item, or first n items of an array. Useful for showing the first test, or a summary of the first N failures in a report.
Parameters:
- array (unknown) - The array from test data.
- n (unknown) - Number of items to return from the start.
Returns: unknown|unknown[] - The first item or first n items.
Example:
`handlebars
{{first test.results 2}}


`
---
#### forEach
Iterates over each item in an array and exposes the current item as context to the inner block. Useful for rendering each test case, log entry, or assertion in a test report.
Parameters:
- array (unknown) - The array from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each item.
Example:
`handlebars
{{#forEach test.results}}
{{this}}
{{/forEach}}


`
---
#### inArray
Block helper that renders the block if an array has the given value. Optionally specify an inverse block to render when the array does not have the value. Useful for conditionally rendering sections if a test status or tag is present in the results.
Parameters:
- array (unknown) - The array from test data.
- value (unknown) - The value to check for.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block if value is present, else inverse.
Example:
`handlebars
{{#inArray test.results "passed"}}foo{{else}}bar{{/inArray}}


`
---
#### isArray
Returns true if value is an ES5 array. Useful for checking if a test field is an array before iterating in a template.
Parameters:
- value (unknown) - The value to test.
Returns: boolean - True if value is an array.
Example:
`handlebars
{{isArray test.results}}


`
---
#### itemAt
Returns the item from array at index idx.
Parameters:
- array (unknown) - The array from test data.
- idx (unknown) - The index to retrieve.
Returns: unknown - The item at the given index.
Example:
`handlebars
{{itemAt test.results 1}}


`
---
#### join
Join all elements of array into a string, optionally using a given separator.
Parameters:
- array (unknown) - The array from test data.
- separator (unknown) - The separator to use. Defaults to ','.
Returns: string - The joined string.
Example:
`handlebars
{{join test.results}}


{{join test.results "-"}}

`
---
#### equalsLength
Returns true if the length of the given value is equal to the given length. Can be used as a block or inline helper.
Parameters:
- value (unknown) - The value to test (array or string).
- length (unknown) - The length to compare to.
Returns: boolean - True if lengths are equal.
Example:
`handlebars
{{equalsLength test.results 2}}


`
---
#### last
Returns the last item, or last n items in an array or string. Opposite of first.
Parameters:
- value (unknown) - The array or string from test data.
- n (unknown) - Number of items to return from the end.
Returns: unknown|unknown[] - The last item or last n items.
Example:
`handlebars
{{last test.results}}


{{last test.results 2}}

`
---
#### slice
Returns a slice of an array from the specified start index to the end index. Useful for pagination, limiting displayed items, or working with specific ranges of test results.
Parameters:
- array (unknown) - The array to be sliced.
- start (unknown) - The start index for the slice.
- end (unknown) - The end index for the slice (exclusive).
- options (object) - Handlebars options object, including the block to render.
Returns: string - A concatenated string of all rendered items within the slice.
Example:
`handlebars
{{#slice test.results 1 4}}
{{this.name}}

{{/slice}}


`
---
#### length
Returns the length of the given string or array.
Parameters:
- value (unknown) - The value to measure (array, object, or string).
Returns: number - The length of the value.
Example:
`handlebars
{{length test.results}}


`
---
#### map
Alias for equalsLength. / export const lengthEqualHelper = equalsLengthHelper; /** Returns a new array, created by calling function on each element of the given array.
Parameters:
- array (unknown) - The array from test data.
- fn (unknown) - The function to call on each element.
Returns: unknown[] - The mapped array.
Example:
`handlebars
{{map test.results double}}


`
---
#### pluck
Map over the given object or array of objects and create an array of values from the given prop. Dot-notation may be used (as a string) to get nested properties.
Parameters:
- collection (unknown) - The array or object from test data.
- prop (unknown) - The property to pluck (dot notation allowed).
Returns: unknown[] - The plucked values.
Example:
`handlebars
{{pluck test.results "name"}}


`
---
#### reverse
Reverse the elements in an array, or the characters in a string.
Parameters:
- value (unknown) - The array or string from test data.
Returns: unknown - The reversed array or string.
Example:
`handlebars
{{reverse test.results}}


`
---
#### some
Block helper that returns the block if the callback returns true for some value in the given array.
Parameters:
- array (unknown) - The array from test data.
- iter (unknown) - The iteratee function.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block if some item passes the iteratee.
Example:
`handlebars
{{#some test.results isString}}
Render me if the array has a string.
{{else}}
Render me if it doesn't.
{{/some}}
`
---
#### sort
Sort the given array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.
Parameters:
- array (unknown) - The array from test data.
- keyOrFn (unknown) - The key to sort by, or a sorting function.
Returns: unknown[] - The sorted array.
Example:
`handlebars
{{sort test.results}}


`
---
#### sortBy
Sort an array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.
Parameters:
- array (unknown) - The array from test data.
- props (unknown) - The property or properties to sort by.
Returns: unknown[] - The sorted array.
Example:
`handlebars
{{sortBy test.results "score"}}


`
---
#### withAfter
Use the items in the array after the specified index as context inside a block. Opposite of withBefore.
Parameters:
- array (unknown) - The array from test data.
- idx (unknown) - The index after which to use items.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for items after idx.
Example:
`handlebars
{{#withAfter test.results 2}}
{{this}}
{{/withAfter}}


`
---
#### withBefore
Use the items in the array before the specified index as context inside a block. Opposite of withAfter.
Parameters:
- array (unknown) - The array from test data.
- idx (unknown) - The index before which to use items.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for items before idx.
Example:
`handlebars
{{#withBefore test.results 2}}
{{this}}
{{/withBefore}}


`
---
#### withFirst
Use the first item in a collection inside a handlebars block expression. Opposite of withLast.
Parameters:
- array (unknown) - The array from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for the first item.
Example:
`handlebars
{{#withFirst test.results}}
{{this}}
{{/withFirst}}


`
---
#### withGroup
Block helper that groups array elements by given group size.
Parameters:
- array (unknown) - The array from test data.
- size (unknown) - The desired length of each group.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each group.
Example:
`handlebars
{{#withGroup test.results 2}}
{{#each this}}
{{.}}
{{/each}}


{{/withGroup}}


`
---
#### withLast
Use the last item or n items in an array as context inside a block. Opposite of withFirst.
Parameters:
- array (unknown) - The array from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for the last item.
Example:
`handlebars
{{#withLast test.results}}
{{this}}
{{/withLast}}


`
---
#### withSort
Block helper that sorts a collection and exposes the sorted collection as context inside the block.
Parameters:
- array (unknown) - The array from test data.
- prop (unknown) - The property to sort by.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for sorted items.
Example:
`handlebars
{{#withSort test.results "score"}}{{this}}{{/withSort}}


`
---
#### unique
Block helper that returns an array with all duplicate values removed. Best used along with an each helper.
Parameters:
- array (unknown) - The array from test data.
Returns: unknown[] - Array with duplicates removed.
Example:
`handlebars
{{#each (unique test.results)}}{{.}}{{/each}}


`
---
$3
#### isEmpty
Checks if a collection (array, object, or string) is empty. Inline, subexpression, or block helper that returns true (or the block) if the given collection is empty, or false (or the inverse block, if supplied) if the collection is not empty. Useful in CTRF test reporting for conditionally rendering sections when there are no tests, errors, or results.
Parameters:
- collection (unknown) - The collection (array, object, or string) to check.
- options (unknown) - Handlebars options object (for block usage).
Returns: boolean|string - True/false for inline/subexpression, or rendered block for block usage.
Example:
`handlebars
{{#isEmpty test.results}}No results!{{else}}Results found.{{/isEmpty}}

{{isEmpty test.errors}}

`
---
#### iterate
Block helper that iterates over an array or object, exposing each item (and key for objects) to the block. If an array is given, .forEach is called; if an object is given, .forOwn is called; otherwise the inverse block is returned. Useful in CTRF test reporting for iterating over dynamic test results, error maps, or grouped data.
Parameters:
- collection (unknown) - The collection (array or object) to iterate over.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each item, or inverse block if not iterable.
Example:
`handlebars
{{#iterate test.results}}
Test: {{this.name}} - Status: {{this.status}}
{{else}}
No test results.
{{/iterate}}

{{#iterate test.stats}}
{{@key}}: {{this}}
{{/iterate}}

`
---
$3
#### and
Helper that renders the block if both of the given values are truthy. If an inverse block is specified it will be rendered when falsy. Works as a block helper, inline helper or subexpression.
Example:
`handlebars
{{#and test.passed (not test.flaky)}}Test is stable and passed{{else}}Unstable or failed{{/and}}
Use to show a message only if a test both passed and is not flaky in a CTRF report.
`
---
#### compare
Render a block when a comparison of the first and third arguments returns true. The second argument is the arithmetic operator to use. You may also optionally specify an inverse block to render when falsy.
Example:
`handlebars
{{#compare test.duration ">" 1000}}Long-running test{{else}}Quick test{{/compare}}
Use to highlight tests that exceed a duration threshold in test reports.
`
---
#### contains
Block helper that renders the block if collection has the given value, using strict equality (===) for comparison, otherwise the inverse block is rendered (if specified). If a startIndex is specified and is negative, it is used as the offset from the end of the collection.
Example:
`handlebars
{{#contains test.tags "flaky"}}Flaky test{{else}}Stable test{{/contains}}
Use to check if a test's tags include "flaky" or another status in a CTRF report.
`
---
#### default
Returns the first value that is not undefined, otherwise the default value is returned.
Example:
`handlebars
{{default test.error "No error message"}}
Use to provide fallback text for missing error messages in test reports.
`
---
#### eq
Block helper that renders a block if a is equal to b. If an inverse block is specified it will be rendered when falsy. You may optionally use the compare="" hash argument for the second value.
Example:
`handlebars
{{#eq test.status "passed"}}✓ Passed{{else}}✗ Failed{{/eq}}
Use to show a checkmark for passed tests and a cross for failed ones in a CTRF summary.
`
---
#### gt
Block helper that renders a block if a is greater than b. If an inverse block is specified it will be rendered when falsy. You may optionally use the compare="" hash argument for the second value.
Example:
`handlebars
{{#gt test.duration 2000}}Test took longer than 2s{{else}}Test was quick{{/gt}}
Use to highlight slow tests in a test duration report.
`
---
#### gte
Block helper that renders a block if a is greater than or equal to b. If an inverse block is specified it will be rendered when falsy. You may optionally use the compare="" hash argument for the second value.
Example:
`handlebars
{{#gte test.retries 1}}Test was retried{{else}}No retries{{/gte}}
Use to show a warning if a test was retried at least once in a CTRF report.
`
---
#### has
Block helper that renders a block if value has pattern. If an inverse block is specified it will be rendered when falsy.
Example:
`handlebars
{{#has test.message "timeout"}}Timeout error detected{{else}}No timeout{{/has}}
Use to check if a test's error message contains a specific keyword in a report.
`
---
#### isFalsey
Returns true if the given value is falsey. Uses JS falsey semantics.
Example:
`handlebars
{{#if (isFalsey test.error)}}No error present{{/if}}
Use to check if a test has no error message in a summary table.
`
---
#### isTruthy
Returns true if the given value is truthy. Uses JS truthy semantics.
Example:
`handlebars
{{#if (isTruthy test.passed)}}Test passed{{/if}}
Use to check if a test passed in a conditional block.
`
---
#### ifEven
Return true if the given value is an even number.
Example:
`handlebars
{{#ifEven @index}}Even row{{else}}Odd row{{/ifEven}}
Use to alternate row colors in a test report table by index.
`
---
#### ifNth
Conditionally renders a block if the remainder is zero when a operand is divided by b. If an inverse block is specified it will be rendered when the remainder is not zero.
Example:
`handlebars
{{#ifNth @index 3}}Every third row{{/ifNth}}
Use to highlight every nth test in a report table.
`
---
#### ifOdd
Block helper that renders a block if value is an odd number. If an inverse block is specified it will be rendered when falsy.
Example:
`handlebars
{{#ifOdd @index}}Odd row{{else}}Even row{{/ifOdd}}
Use to alternate row colors in a test report table by index.
`
---
#### is
Block helper that renders a block if a is equal to b. If an inverse block is specified it will be rendered when falsy. Similar to eq but does not do strict equality.
Example:
`handlebars
{{#is test.status 1}}Loose match for status{{/is}}
Use for loose equality checks on test status or codes in a report.
`
---
#### isnt
Block helper that renders a block if a is not equal to b. If an inverse block is specified it will be rendered when falsy. Similar to unlessEq but does not use strict equality for comparisons.
Example:
`handlebars
{{#isnt test.status "failed"}}Not failed{{/isnt}}
Use to show a message for tests that are not failed in a summary.
`
---
#### lt
Block helper that renders a block if a is less than b. If an inverse block is specified it will be rendered when falsy. You may optionally use the compare="" hash argument for the second value.
Example:
`handlebars
{{#lt test.duration 500}}Very fast test{{else}}Not very fast{{/lt}}
Use to highlight tests that are especially quick in a report.
`
---
#### lte
Block helper that renders a block if a is less than or equal to b. If an inverse block is specified it will be rendered when falsy. You may optionally use the compare="" hash argument for the second value.
Example:
`handlebars
{{#lte test.retries 0}}No retries{{else}}Retried{{/lte}}
Use to show a message for tests that were not retried in a CTRF report.
`
---
#### neither
Block helper that renders a block if neither of the given values are truthy. If an inverse block is specified it will be rendered when falsy.
Example:
`handlebars
{{#neither test.passed test.retryPassed}}Both failed{{/neither}}
Use to check if both a test and its retry failed in a report.
`
---
#### not
Returns true if val is falsey. Works as a block or inline helper.
Example:
`handlebars
{{#not test.passed}}Test failed{{/not}}
Use to show a message for failed tests in a summary table.
`
---
#### or
Block helper that renders a block if any of the given values is truthy. If an inverse block is specified it will be rendered when falsy.
Example:
`handlebars
{{#or test.failed test.flaky}}Attention needed{{/or}}
Use to show a warning if a test is either failed or flaky in a CTRF report.
`
---
#### unlessEq
Block helper that always renders the inverse block unless a is is equal to b.
Example:
`handlebars
{{#unlessEq test.status "failed"}}Not failed{{/unlessEq}}
Use to show a message for tests that are not failed in a CTRF report.
`
---
#### unlessGt
Block helper that always renders the inverse block unless a is is greater than b.
Example:
`handlebars
{{#unlessGt test.duration 1000}}Not long{{/unlessGt}}
Use to show a message for tests that are not long-running in a report.
`
---
#### unlessLt
Block helper that always renders the inverse block unless a is is less than b.
Example:
`handlebars
{{#unlessLt test.duration 500}}Not very fast{{/unlessLt}}
Use to show a message for tests that are not especially quick in a report.
`
---
#### unlessGteq
Block helper that always renders the inverse block unless a is is greater than or equal to b.
Example:
`handlebars
{{#unlessGteq test.retries 1}}No retries{{/unlessGteq}}
Use to show a message for tests that were not retried in a CTRF report.
`
---
#### unlessLteq
Block helper that always renders the inverse block unless a is is less than or equal to b.
Example:
`handlebars
{{#unlessLteq test.retries 0}}Retried at least once{{/unlessLteq}}
Use to show a message for tests that were retried in a CTRF report.
`
---
$3
#### year
Handlebars helper that returns the current year.
Returns: number - The current year (e.g., 2024).
Example:
`handlebars
{{year}}
"date": "{{year}}"
`
---
$3
#### read
Read a file from the file system. Useful for including file contents in CTRF test reports or templates.
Parameters:
- filepath (unknown) - The path to the file to read (relative to process.cwd() or absolute).
Returns: string - The file contents as a string, or an empty string if not found.
Example:
`handlebars
{{read "src/test-data/sample-ctrf-data.ts"}}

{{someHelper (read "output/test-report.html")}}

`
---
#### files
Return an array of files from the given directory. Useful for listing test artifacts, screenshots, or log files in CTRF reports.
Parameters:
- directory (unknown) - The directory path (relative to process.cwd() or absolute).
Returns: string[] - Array of file names in the directory, or an empty array if not found.
Example:
`handlebars
{{#each (files "output/")}}
{{this}}

{{/each}}

`
---
$3
#### getGitHubIcon
Retrieves a GitHub octicon URL for a given test state or category. Useful for creating GitHub-styled test reports, pull request comments, and GitHub Actions outputs.
Parameters:
- status (unknown) - The test state or category to get a GitHub octicon for.
Returns: string - The GitHub octicon URL corresponding to the provided state.
Example:
`handlebars
{{getGitHubIcon "passed"}}

{{getGitHubIcon "failed"}}

{{getGitHubIcon "flaky"}}

{{getGitHubIcon "stats"}}

Use with CTRF templates: Perfect for creating GitHub-styled test reports, pull request status comments, GitHub Actions summaries, and any GitHub-integrated test reporting that needs consistent GitHub octicon iconography.
`
---
#### formatTestPath
Internal function that maps CTRF states and keywords to appropriate GitHub octicon names. Returns URLs to GitHub octicon SVGs hosted on ctrf.io.
Parameters:
- suite (unknown) - The test suite path (may contain spaces or ">" as separators).
- name (unknown) - The test name.
Returns: string - A formatted string with GitHub arrow-right icons between path segments.
Example:
`handlebars
{{formatTestPath "filename.ts > suiteone > suitetwo" "test name"}}

{{formatTestPath suite.name "Login Test"}}

{{formatTestPath "User Tests > Authentication" "should login with valid credentials"}}

Use with CTRF templates: Perfect for creating GitHub-styled test reports, pull request comments, and any documentation that needs clear test path hierarchies with professional arrow separators.
`
---
$3
#### inflect
Returns either the singular or plural inflection of a word based on the given count. Optionally includes the count in the result. Useful for displaying test counts, result summaries, and dynamic messaging in test reports.
Parameters:
- count (unknown) - The count to determine singular/plural form.
- singular (unknown) - The singular form of the word.
- plural (unknown) - The plural form of the word.
- includeCount (unknown) - Optional. If true, includes the count in the result.
Returns: string - The appropriate singular/plural form for use in test reports.
Example:
`handlebars
{{inflect tests.passed.length "test" "tests"}}


{{inflect tests.failed.length "failure" "failures" true}}



{{inflect suite.testCount "case" "cases" true}} found in {{suite.name}}

Use in CTRF templates for dynamic test result messaging:
- Test count summaries: "{{inflect total "test" "tests" true}} executed"
- Error reporting: "{{inflect errors.length "error" "errors"}} detected"
- Suite descriptions: "{{inflect suite.tests.length "test case" "test cases"}}"
`
---
#### ordinalize
Returns an ordinalized number as a string (1st, 2nd, 3rd, etc.). Useful for ranking test results, iteration counts, and positional information in test reports.
Parameters:
- val (unknown) - The number to ordinalize (can be string or number).
Returns: string - The ordinalized number for use in test reports.
Example:
`handlebars
{{ordinalize test.attempt}}



{{ordinalize suite.position}} test suite in the execution order

This is the {{ordinalize test.retry}} retry of {{test.name}}

Use in CTRF templates for:
- Test execution order: "{{ordinalize index}} test executed"
- Retry information: "{{ordinalize retryCount}} attempt"
- Suite positioning: "{{ordinalize position}} suite in batch"
- Ranking results: "{{ordinalize rank}} fastest test"
`
---
$3
#### match
Returns an array of strings that match the given glob pattern(s). Useful for filtering test files, assets, or any file paths in test reports based on patterns.
Parameters:
- files (string[]|string) - Array of file paths or single file path from test data.
- patterns (string|string[]) - One or more glob patterns to match against.
- options (Object) - Handlebars options object (optional).
Returns: string[] - Array of file paths that match the patterns for use in test reports.
Example:
`handlebars
{{match testFiles "*.spec.js"}}
{{match (readdir "tests") "*\/.test.ts"}}
{{match test.artifacts "*.png"}}
Given testFiles: ["auth.test.js", "login.spec.js", "utils.js"]
Results in: ["login.spec.js"]
Use with CTRF templates to filter test files by pattern, extract specific artifacts, or organize test results by file type.
`
---
#### isMatch
Returns true if a filepath contains the given pattern. Useful for conditional logic in test reports to check if files match specific patterns.
Parameters:
- filepath (string) - The file path from test data to check.
- pattern (string) - The glob pattern to match against.
- options (Object) - Handlebars options object (optional).
Returns: boolean - True if the filepath matches the pattern for use in test reports.
Example:
`handlebars
{{isMatch "user-login.spec.ts" ".spec."}}
{{isMatch test.file "*.test.js"}}
Results: true for matching patterns
Use with CTRF templates to conditionally render content based on file patterns, categorize tests by file type, or show different icons for different test categories.
`
---
$3
#### abs
Return the magnitude (absolute value) of a number. Useful for normalizing test durations, error counts, or differences in CTRF reports.
Parameters:
- a (unknown) - The value to get the absolute value of.
Returns: number - The absolute value.
Example:
`handlebars
{{abs test.duration}}


`
---
#### add
Return the sum of a plus b. Useful for aggregating test metrics, such as total retries or combined durations.
Parameters:
- a (unknown) - First number.
- b (unknown) - Second number.
Returns: number - The sum.
Example:
`handlebars
{{add test.duration 100}}


`
---
#### addAll
Adds multiple numbers together and returns the sum. Useful for totaling multiple test metrics or values in a single expression.
Parameters:
- args (...unknown) - The numbers to be added (last argument is Handlebars options).
Returns: number - The sum of all provided numbers.
Example:
`handlebars
{{addAll test.duration test.retries 100}}


{{addAll 1 2 3 4 5}}

`
---
#### avg
Returns the average of all numbers in the given array. Useful for calculating average test durations, retry counts, or error rates in CTRF reports.
Parameters:
- arr (unknown) - Array of numbers (array or JSON string).
Returns: number - The average value.
Example:
`handlebars
{{avg "[1, 2, 3, 4, 5]"}}

`
---
#### ceil
Get the Math.ceil() of the given value. Useful for rounding up test metrics, such as duration or retry counts.
Parameters:
- value (unknown) - The value to ceil.
Returns: number - The ceiled value.
Example:
`handlebars
{{ceil test.duration}}


`
---
#### divide
Divide a by b. Useful for calculating rates, averages, or percentages in CTRF reports.
Parameters:
- a (unknown) - Numerator.
- b (unknown) - Denominator.
Returns: number - The result of division, or 0 if denominator is 0.
Example:
`handlebars
{{divide test.duration test.retries}}


`
---
#### floor
Get the Math.floor() of the given value. Useful for rounding down test metrics, such as duration or retry counts.
Parameters:
- value (unknown) - The value to floor.
Returns: number - The floored value.
Example:
`handlebars
{{floor test.duration}}


`
---
#### minus
Return the difference of a minus b. Useful for calculating deltas between test metrics, such as duration differences.
Parameters:
- a (unknown) - First number.
- b (unknown) - Second number.
Returns: number - The difference.
Example:
`handlebars
{{minus test.duration 10}}


`
---
#### modulo
Get the remainder of a division operation (a % b). Useful for calculating modulo in test metrics, such as grouping or bucketing.
Parameters:
- a (unknown) - Numerator.
- b (unknown) - Denominator.
Returns: number - The remainder.
Example:
`handlebars
{{modulo test.index 3}}


`
---
#### multiply
Return the product of a times b. Useful for scaling test metrics, such as multiplying durations or retry counts.
Parameters:
- a (unknown) - First factor.
- b (unknown) - Second factor.
Returns: number - The product.
Example:
`handlebars
{{multiply test.duration 2}}


`
---
#### plus
Add a by b (alias for add). Useful for summing test metrics.
Parameters:
- a (unknown) - First number.
- b (unknown) - Second number.
Returns: number - The sum.
Example:
`handlebars
{{plus test.duration 5}}


`
---
#### random
Generate a random number between two values (inclusive, integer). Useful for generating random test data or sampling in CTRF reports.
Parameters:
- min (unknown) - Minimum value.
- max (unknown) - Maximum value.
Returns: number - Random integer between min and max.
Example:
`handlebars
{{random 1 10}}

`
---
#### remainder
Get the remainder when a is divided by b (alias for modulo). Useful for grouping or bucketing test metrics.
Parameters:
- a (unknown) - Numerator.
- b (unknown) - Denominator.
Returns: number - The remainder.
Example:
`handlebars
{{remainder test.index 4}}


`
---
#### round
Round the given number to the nearest integer. Useful for rounding test metrics for display in CTRF reports.
Parameters:
- number (unknown) - The number to round.
Returns: number - The rounded value.
Example:
`handlebars
{{round test.duration}}


`
---
#### subtract
Return the difference of a minus b (alias for minus). Useful for calculating deltas between test metrics.
Parameters:
- a (unknown) - First number.
- b (unknown) - Second number.
Returns: number - The difference.
Example:
`handlebars
{{subtract test.duration 5}}


`
---
#### sum
Returns the sum of all numbers in the given array. Useful for calculating total durations, retries, or error counts in CTRF reports.
Parameters:
- arr (unknown) - Array of numbers (array or JSON string).
Returns: number - The sum.
Example:
`handlebars
{{sum "[1, 2, 3, 4, 5]"}}

`
---
#### times
Multiply number a by number b (alias for multiply). Useful for scaling test metrics.
Parameters:
- a (unknown) - First factor.
- b (unknown) - Second factor.
Returns: number - The product.
Example:
`handlebars
{{times test.duration 3}}


`
---
$3
#### option
Return the given value of prop from this.options. Useful for accessing runtime options passed to the template, such as CTRF configuration or test report metadata.
Parameters:
- prop (string) - The dot-notated property path to retrieve from this.options.
Returns: any - The value at the given property path, or undefined if not found.
Example:
`handlebars
{{option "a.b.c"}}

`
---
#### noop
Block helper that renders the block without taking any arguments. Useful for grouping content or as a placeholder in CTRF test report templates.
Parameters:
- options (object) - Handlebars options object.
Returns: string - The rendered block content.
Example:
`handlebars
{{#noop}}
This block is always rendered.
{{/noop}}
`
---
#### typeOf
Get the native type of the given value. Useful for debugging or conditional logic in CTRF test report templates.
Parameters:
- value (any) - The value to check.
Returns: string - The native type of the value.
Example:
`handlebars
{{typeOf 1}}         //=> 'number'
{{typeOf "foo"}}     //=> 'string'
{{typeOf test.data}} //=> 'object'
`
---
#### withHash
Block helper that builds the context for the block from the options hash. Useful for injecting dynamic context in CTRF test report templates.
Parameters:
- options (object) - Handlebars options object with hash.
Returns: string - The rendered block with hash context.
Example:
`handlebars
{{#withHash foo="bar" count=3}}
Foo: {{foo}}, Count: {{count}}
{{/withHash}}

`
---
$3
#### bytes
Format a number to its equivalent in bytes. If a string is passed, its length will be formatted and returned. Useful for displaying test file sizes, memory usage, or data transfer amounts in test reports.
Parameters:
- number (unknown) - The number or string from test data to format as bytes.
Returns: string - The formatted byte string for use in test reports.
Example:
`handlebars
{{bytes test.stats.totalFileSize}}


{{bytes test.name}}


{{bytes test.stats.coverageSize}}


Use with CTRF templates: Perfect for displaying test artifact sizes, log file sizes, or memory consumption metrics in test reports.
`
---
#### addCommas
Add commas to numbers for improved readability. Useful for formatting large numbers like test counts, execution times, or file sizes in test reports.
Parameters:
- num (unknown) - The number from test data to format with commas.
Returns: string - The comma-formatted number string for use in test reports.
Example:
`handlebars
{{addCommas test.stats.totalTests}}


{{addCommas test.duration}}


{{addCommas test.stats.assertions}}


Use with CTRF templates: Essential for making large test metrics readable, such as total test counts, assertion counts, or execution times in milliseconds.
`
---
#### phoneNumber
Convert a string or number to a formatted phone number. Useful for formatting contact information in test reports or user data validation tests.
Parameters:
- num (unknown) - The phone number from test data to format, e.g., 8005551212.
Returns: string - Formatted phone number: (800) 555-1212 for use in test reports.
Example:
`handlebars
{{phoneNumber test.user.phone}}


{{phoneNumber "5551234567"}}

{{phoneNumber test.contactInfo.emergencyPhone}}

Use with CTRF templates: Useful when testing applications with user registration, contact forms, or when displaying formatted test data that includes phone numbers.
`
---
#### abbreviateNumber
Abbreviate numbers to the given number of precision. This is for general numbers, not size in bytes. Useful for displaying large test metrics like execution counts or performance numbers in test reports.
Parameters:
- number (unknown) - The number from test data to abbreviate.
- precision (unknown) - The number of decimal places to show.
Returns: string - The abbreviated number string for use in test reports.
Example:
`handlebars
{{abbreviateNumber test.stats.totalAssertions "2"}}


{{abbreviateNumber test.performance.opsPerSecond "1"}}


{{abbreviateNumber test.stats.memoryUsage "3"}}


Use with CTRF templates: Perfect for dashboard displays showing abbreviated test metrics, performance indicators, or large statistical values without overwhelming the report layout.
`
---
#### toExponential
Returns a string representing the given number in exponential notation. Useful for displaying very large or very small test metrics and scientific notation in test reports.
Parameters:
- number (unknown) - The number from test data to convert to exponential notation.
- fractionDigits (unknown) - Optional. The number of digits after the decimal point.
Returns: string - The exponential notation string for use in test reports.
Example:
`handlebars
{{toExponential test.stats.totalExecutions}}


{{toExponential test.performance.nanoseconds "2"}}


{{toExponential test.stats.bigNumber "4"}}

Use with CTRF templates: Ideal for scientific test data, performance benchmarks with extreme values, or when displaying test results that involve very large or very small numbers.
`
---
#### toFixed
Formats the given number using fixed-point notation. Useful for displaying consistent decimal precision in test metrics, percentages, and measurements in test reports.
Parameters:
- number (unknown) - The number from test data to format with fixed-point notation.
- digits (unknown) - Optional. The number of digits after the decimal point (0-20).
Returns: string - The fixed-point formatted string for use in test reports.
Example:
`handlebars
{{toFixed test.coverage.percentage "2"}}


{{toFixed test.performance.avgResponseTime "3"}}


{{toFixed test.stats.successRate "1"}}


Use with CTRF templates: Essential for displaying consistent formatting of percentages, timing data, success rates, and any decimal values in test reports.
`
---
#### toPrecision
Returns a string representing the Number object to the specified precision. Useful for displaying test metrics with consistent significant digits and scientific precision in test reports.
Parameters:
- number (unknown) - The number from test data to format with specified precision.
- precision (unknown) - Optional. The number of significant digits (1-100).
Returns: string - The precision-formatted string for use in test reports.
Example:
`handlebars
{{toPrecision test.performance.throughput "3"}}


{{toPrecision test.stats.memoryUsage "5"}}


{{toPrecision test.timing.duration "2"}}


Use with CTRF templates: Perfect for displaying performance metrics, scientific test data, or any values where you need consistent significant digit precision across different scales.
`
---
#### toPercent
Converts a decimal rate (0-1) to a percentage with fixed decimal places. This is specifically for rates from the CTRF insights that are calculated as decimals. Useful for displaying test success rates, failure rates, flaky rates, and coverage percentages in test reports.
Parameters:
- rate (unknown) - The numeric rate as a decimal (0-1) from test data.
- fractionDigits (unknown) - Optional. The number of decimal places (0-20). Defaults to 2.
Returns: string - The formatted percentage string for use in test reports.
Example:
`handlebars
{{toPercent test.stats.successRate 2}}


{{toPercent test.coverage.failRate 1}}


{{toPercent test.performance.flakyRate 3}}


Use with CTRF templates: Essential for displaying test rates, success/failure percentages, coverage metrics, and any decimal values that represent ratios as readable percentages in test reports.
`
---
$3
#### extend
Extend the context with the properties of other objects. A shallow merge is performed to avoid mutating the context. Useful for combining test metadata, configuration objects, and report data in CTRF templates.
Parameters:
- context (unknown) - The base context object from test data.
- objects (...unknown) - One or more objects to extend with.
Returns: Record - The extended object for use in test reports.
Example:
`handlebars
{{extend test.metadata test.config}}

{{extend test.results test.summary}}

`
---
#### forIn
Block helper that iterates over the properties of an object, exposing each key and value on the context. Useful for rendering test metadata, configuration settings, or nested test data in CTRF reports.
Parameters:
- context (unknown) - The object to iterate over from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each property with key and value exposed.
Example:
`handlebars
{{#forIn test.metadata}}
{{@key}}: {{this}}
{{/forIn}}

{{#forIn test.config}}
{{@key}}{{this}}
{{/forIn}}

`
---
#### forOwn
Block helper that iterates over the own properties of an object, exposing each key and value on the context. Useful for rendering test-specific data without inherited properties in CTRF reports.
Parameters:
- obj (unknown) - The object to iterate over from test data.
- options (unknown) - Handlebars options object.
Returns: string - Rendered block for each own property with key and value exposed.
Example:
`handlebars
{{#forOwn test.results}}
{{@key}}: {{this}}
{{/forOwn}}

{{#forOwn test.metadata}}
{{@key}}: {{this}}

{{/forOwn}}

`
---
#### toPath
Take arguments and, if they are string or number, convert them to a dot-delineated object property path. Useful for creating dynamic property paths for accessing nested test data in CTRF reports.
Parameters:
- props (...unknown) - The property segments to assemble (can be multiple).
Returns: string - The dot-delineated property path for use in test reports.
Example:
`handlebars
{{toPath "test" "results" "status"}}

{{toPath "suite" 0 "name"}}

`
---
#### get
Use property paths (a.b.c) to get a value or nested value from the context. Works as a regular helper or block helper. Useful for accessing deeply nested test data, configuration values, or metadata in CTRF reports.
Parameters:
- prop (unknown) - The property to get, optionally using dot notation for nested properties.
- context (unknown) - The context object from test data.
- options (unknown) - The handlebars options object, if used as a block helper.
Returns: unknown - The retrieved value for use in test reports.
Example:
`handlebars
{{get "test.results.status" test}}

{{get "suite.tests.0.name" data}}

{{#get "test.metadata" test}}
{{this}}
{{/get}}

`
---
#### getObject
Use property paths (a.b.c) to get an object from the context. Differs from the get helper in that this helper will return the actual object, including the given property key. Also, this helper does not work as a block helper. Useful for accessing parent objects or containers in CTRF reports.
Parameters:
- prop (unknown) - The property to get, optionally using dot notation for nested properties.
- context (unknown) - The context object from test data.
Returns: unknown - The retrieved object for use in test reports.
Example:
`handlebars
{{getObject "test.results" test}}

{{getObject "suite.tests" data}}

`
---
#### hasOwn
Return true if key is an own, enumerable property of the given context object. Useful for conditional logic and validation in CTRF report templates.
Parameters:
- context (unknown) - The context object from test data.
- key (unknown) - The property key to check.
Returns: boolean - True if the key is an own, enumerable property for use in test reports.
Example:
`handlebars
{{hasOwn test "status"}}

{{#if (hasOwn test.metadata "priority")}}
Priority: {{test.metadata.priority}}
{{/if}}

`
---
#### isObject
Return true if value is an object. Useful for conditional logic and type checking in CTRF report templates.
Parameters:
- value (unknown) - The value from test data to check.
Returns: boolean - True if the value is an object for use in test reports.
Example:
`handlebars
{{isObject test.results}}

{{isObject "string"}}

{{#if (isObject test.metadata)}}
{{#forIn test.metadata}}
{{@key}}: {{this}}
{{/forIn}}
{{/if}}

`
---
#### JSONparse
Parses the given string using JSON.parse. Useful for parsing JSON strings from test data, configuration, or API responses in CTRF reports.
Parameters:
- string (unknown) - The string to parse from test data.
- options (unknown) - Handlebars options object for block usage.
Returns: unknown - The parsed object for use in test reports.
Example:
`handlebars
{{JSONparse test.jsonData}}


{{#JSONparse test.configString}}
{{status}} - {{duration}}ms
{{/JSONparse}}

`
---
#### JSONstringify
Stringify an object using JSON.stringify. Useful for serializing test data, configuration objects, or complex data structures in CTRF reports.
Parameters:
- obj (unknown) - Object to stringify from test data.
Returns: string - The JSON string for use in test reports.
Example:
`handlebars
{{JSONstringify test.results}}


{{JSONstringify test.metadata}}

`
---
#### merge
Deeply merge the properties of the given objects with the context object. Useful for combining test data, configuration, and metadata with deep merging in CTRF reports.
Parameters:
- object (unknown) - The target object. Pass an empty object to shallow clone.
- objects (...unknown) - Additional objects to merge.
Returns: Record - The merged object for use in test reports.
Example:
`handlebars
{{merge test.results test.metadata}}

{{merge {} test.config test.overrides}}

`
---
#### pick
Pick properties from the context object. Useful for selecting specific test data fields, creating filtered views, or extracting relevant information in CTRF reports.
Parameters:
- properties (unknown) - One or more properties to pick.
- context (unknown) - The context object from test data.
- options (unknown) - Handlebars options object.
Returns: unknown - Returns an object with the picked values. If used as a block helper, the values are passed as context to the inner block. If no values are found, the context is passed to the inverse block.
Example:
`handlebars
{{pick test "name" "status" "duration"}}

{{#pick test.metadata "priority" "category"}}
{{priority}} - {{category}}
{{/pick}}

{{#pick test.results "passed" "failed"}}
Passed: {{passed}}, Failed: {{failed}}
{{else}}
No results available
{{/pick}}

``
---
$3