jest-metadata
v1.5.4
Published
🦸♂️ Superhero power for your Jest reporters! 🦸♀️
Downloads
16,438
Maintainers
Readme
jest-metadata
🦸♂️ Superhero power for your Jest reporters! 🦸♀️
jest-metadata
is a library that allows you to attach user-defined data to any jest-circus
entity like describe blocks, function definitions, test runs, invocations, and more. Custom reporters can access your custom data to produce rich and insightful reports leveraging low-level details from jest-circus
events and any additional data you want to use in your reports.
🌟 Features
- Attach custom metadata to Jest entities such as describe blocks, function definitions, test runs, and invocations.
- Access your metadata from your reporters to generate insightful reports.
- Graceful degradation for default test environments (
node
,jsdom
) andjest-jasmine2
test runner. - Custom test environment support via a decorator class.
📚 Guidelines
This library is primarily intended for the authors of custom Jest reporters.
Direct usage of jest-metadata
in test files is not recommended.
To use jest-metadata
, you should:
- Declare
jest
as a peer dependency (or direct one) in your package. - Provide your reporter as a class that inherits from
jest-metadata/reporter
. - Provide your test environment as a decorator class that can inherit from any
WithMetadata(*)
class. - Think about using a namespace for your metadata, so it doesn't clash with other metadata.
The best live example of how to use jest-metadata
at the moment is jest-allure2-reporter.
🚀 Quick Start
To get your hands dirty, you can try out jest-metadata
directly in your project.
Install jest-metadata
using npm:
npm install jest-metadata --save-dev
In your Jest config, add the following:
+ "testEnvironment": "jest-metadata/environment-node",
+ "reporters": [
+ "default",
+ "./your-custom-reporter.js",
+ ],
If you need to use jest-metadata
in a JSDOM environment or another custom test environment,
please refer to the Integrating jest-metadata
into test environment guide.
📖 Usage
In a Test File
Attach metadata to test entities using annotations:
import { metadata, $Set } from 'jest-metadata';
// Write your own DSL for attaching metadata to test entities
// Try to namespace your metadata to avoid collisions with other libraries
const $Description = (text) => $Set('mycompany.description', text);
$Description('This is a sample test suite.');
describe('Login flow', () => {
$Description('This is a login test.');
it('should login', () => {
// ...
metadata.push('mycompany.attachements', [
{ name: 'screenshot', type: 'image/png', filePath: '/path/to/screenshot.png' },
]);
// ...
});
});
In a Custom Reporter
Access metadata in a custom Jest reporter:
import { state } from 'jest-metadata';
import { JestMetadataReporter } from 'jest-metadata/reporter';
class CustomReporter extends JestMetadataReporter {
async onTestCaseResult(test, testCaseResult) {
await super.onTestCaseResult(test, testCaseResult);
const metadata = state.getTestFileMetadata(test.path).lastTestEntry;
const titles = [testCaseResult.title, ...testCaseResult.ancestorTitles.slice().reverse()];
const descriptions = [metadata, ...metadata.ancestors()].map((m) => m.get('mycompany.description', '')).find(x => x);
const attachments = [metadata, ...metadata.ancestors()].flatMap((m) => m.get('mycompany.attachements', []));
const n = titles.length;
for (let i = n - 1; i >= 0; i--) {
console.log(`${titles[i]}: ${descriptions[i]}`);
}
// Output:
// > Login flow: This is a sample test suite.
// > should login: This is a login test.
}
}
📄 Documentation
For more detailed documentation and examples, see the docs
folder.
🌐 Contributing
We welcome contributions from the community! To get involved, please follow these steps:
- Check the GitHub issues for open tasks or submit a new issue if you have a feature request or bug report.
- Fork the repository and create a new branch for your changes.
- Make your changes and submit a pull request.
For more information, see our Contribution Guidelines.
📃 License
This project is licensed under the MIT License.