mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
127 lines
4.6 KiB
Plaintext
127 lines
4.6 KiB
Plaintext
---
|
|
title: Test Reporters
|
|
description:
|
|
---
|
|
|
|
bun test supports different output formats through reporters. This document covers both built-in reporters and how to implement your own custom reporters.
|
|
|
|
---
|
|
|
|
## Built-in Reporters
|
|
|
|
### Default Console Reporter
|
|
|
|
By default, bun test outputs results to the console in a human-readable format:
|
|
|
|
```sh terminal icon="terminal"
|
|
test/package-json-lint.test.ts:
|
|
✓ test/package.json [0.88ms]
|
|
✓ test/js/third_party/grpc-js/package.json [0.18ms]
|
|
✓ test/js/third_party/svelte/package.json [0.21ms]
|
|
✓ test/js/third_party/express/package.json [1.05ms]
|
|
|
|
4 pass
|
|
0 fail
|
|
4 expect() calls
|
|
Ran 4 tests in 1.44ms
|
|
```
|
|
|
|
When a terminal doesn't support colors, the output avoids non-ascii characters:
|
|
|
|
```sh terminal icon="terminal"
|
|
test/package-json-lint.test.ts:
|
|
(pass) test/package.json [0.48ms]
|
|
(pass) test/js/third_party/grpc-js/package.json [0.10ms]
|
|
(pass) test/js/third_party/svelte/package.json [0.04ms]
|
|
(pass) test/js/third_party/express/package.json [0.04ms]
|
|
|
|
4 pass
|
|
0 fail
|
|
4 expect() calls
|
|
Ran 4 tests across 1 files. [0.66ms]
|
|
```
|
|
|
|
### Dots Reporter
|
|
|
|
The dots reporter shows `.` for passing tests and `F` for failures—useful for large test suites.
|
|
|
|
```sh terminal icon="terminal"
|
|
bun test --dots
|
|
bun test --reporter=dots
|
|
```
|
|
|
|
### JUnit XML Reporter
|
|
|
|
For CI/CD environments, Bun supports generating JUnit XML reports. JUnit XML is a widely-adopted format for test results that can be parsed by many CI/CD systems, including GitLab, Jenkins, and others.
|
|
|
|
#### Using the JUnit Reporter
|
|
|
|
To generate a JUnit XML report, use the `--reporter=junit` flag along with `--reporter-outfile` to specify the output file:
|
|
|
|
```sh terminal icon="terminal"
|
|
bun test --reporter=junit --reporter-outfile=./junit.xml
|
|
```
|
|
|
|
This continues to output to the console as usual while also writing the JUnit XML report to the specified path at the end of the test run.
|
|
|
|
#### Configuring via bunfig.toml
|
|
|
|
You can also configure the JUnit reporter in your `bunfig.toml` file:
|
|
|
|
```toml title="bunfig.toml" icon="settings"
|
|
[test.reporter]
|
|
junit = "path/to/junit.xml" # Output path for JUnit XML report
|
|
```
|
|
|
|
#### Environment Variables in JUnit Reports
|
|
|
|
The JUnit reporter automatically includes environment information as `<properties>` in the XML output. This can be helpful for tracking test runs in CI environments.
|
|
|
|
Specifically, it includes the following environment variables when available:
|
|
|
|
| Environment Variable | Property Name | Description |
|
|
| ----------------------------------------------------------------------- | ------------- | ---------------------- |
|
|
| `GITHUB_RUN_ID`, `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `CI_JOB_URL` | `ci` | CI build information |
|
|
| `GITHUB_SHA`, `CI_COMMIT_SHA`, `GIT_SHA` | `commit` | Git commit identifiers |
|
|
| System hostname | `hostname` | Machine hostname |
|
|
|
|
This makes it easier to track which environment and commit a particular test run was for.
|
|
|
|
#### Current Limitations
|
|
|
|
The JUnit reporter currently has a few limitations that will be addressed in future updates:
|
|
|
|
- `stdout` and `stderr` output from individual tests are not included in the report
|
|
- Precise timestamp fields per test case are not included
|
|
|
|
### GitHub Actions reporter
|
|
|
|
Bun test automatically detects when it's running inside GitHub Actions and emits GitHub Actions annotations to the console directly. No special configuration is needed beyond installing Bun and running `bun test`.
|
|
|
|
For a GitHub Actions workflow configuration example, see the [CI/CD integration](/pm/cli/install#ci%2Fcd) section of the CLI documentation.
|
|
|
|
---
|
|
|
|
## Custom Reporters
|
|
|
|
Bun allows developers to implement custom test reporters by extending the WebKit Inspector Protocol with additional testing-specific domains.
|
|
|
|
### Inspector Protocol for Testing
|
|
|
|
To support test reporting, Bun extends the standard WebKit Inspector Protocol with two custom domains:
|
|
|
|
1. **TestReporter**: Reports test discovery, execution start, and completion events
|
|
2. **LifecycleReporter**: Reports errors and exceptions during test execution
|
|
|
|
These extensions allow you to build custom reporting tools that can receive detailed information about test execution in real-time.
|
|
|
|
### Key Events
|
|
|
|
Custom reporters can listen for these key events:
|
|
|
|
- `TestReporter.found`: Emitted when a test is discovered
|
|
- `TestReporter.start`: Emitted when a test starts running
|
|
- `TestReporter.end`: Emitted when a test completes
|
|
- `Console.messageAdded`: Emitted when console output occurs during a test
|
|
- `LifecycleReporter.error`: Emitted when an error or exception occurs
|