docs: minor improvements

.gitignore

@@ -106,6 +106,7 @@ dist
 
 # IDE-related
 .idea
+!.idea/icon.svg
 .vscode
 
 # Generated content

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# CONTRIBUTING
+
+We welcome issues and pull requests from the community. :purple_heart:
+
+## Issues
+
+Open an issue on the [issue tracker].
+
+There a few issue templates to choose from, where you will find instructions on how to report a bug or request a feature.
+
+## Pull requests
+
+There are no strict rules for pull requests, but we recommend the following:
+
+* Open an issue first, and discuss your idea with the maintainers.
+* Fork the repository and create a new branch for your changes.
+* Make your changes and submit a pull request.
+* Add tests for your changes.
+* Update the documentation.
+
+### Setup
+
+This is a standard Node.js project. You'll need to have Node.js installed.
+
+Fork this repository, clone and install dependencies:
+
+```bash
+npm install
+```
+
+### Running unit tests
+
+```bash
+npm test
+```
+
+### Running integration tests
+
+```bash
+cd e2e
+npm install
+npm run build
+```
+
+The last command will record snapshots (fixtures) for the integration tests.
+Make sure they don't change unexpectedly.
+If there are changes, review them and re-run unit tests:
+
+```bash
+cd ..
+npm test -- -u # Update snapshots
+```
+
+### Checking your code
+
+Before committing, run the linter and tests:
+
+```bash
+npm run lint
+npm test
+```
+
+To create a commit, use [Commitizen]:
+
+```bash
+npx cz
+```
+
+and follow the instructions. We adhere to Angular's [commit message guidelines].
+
+Thanks in advance for your contribution!
+
+[commit message guidelines]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit
+[issue tracker]: https://github.com/wix-incubator/jest-metadata/issues
+[Commitizen]: https://github.com/commitizen/cz-cli

docs/README.md → README.md

@@ -2,14 +2,13 @@
 
 <div align="center">
 
-<img src="images/logo.png" width=256 height=256 />
+<img src=".idea/icon.svg" width=256 height=256 />
 
 # jest-metadata
 
-Share your custom data across all Jest contexts.
+🦸‍♂️ Superhero powers for your Jest reporter! 🦸‍♀️
 
 [![npm version](https://badge.fury.io/js/jest-metadata.svg?rnd=42)](https://badge.fury.io/js/jest-metadata)
-![test coverage](images/coverage.svg)
 
 </div>
 
@@ -18,19 +17,27 @@ Share your custom data across all Jest contexts.
 ## 🌟 Features
 
 * Attach custom metadata to Jest entities such as describe blocks, function definitions, test runs, and invocations.
-* Access metadata from custom reporters to generate insightful reports.
-* Integrate seamlessly with Jest Circus events.
-* Easy-to-use API for adding and retrieving metadata.
+* Access your metadata from your reporters to generate insightful reports.
+* Graceful degradation for default test environments (`node`, `jsdom`) and `jest-jasmine2` test runner.
+* Custom test environment support via a decorator class.
 
-## 📚 Prerequisites
+## 📚 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:
 
-* Have `jest-circus` as Jest test runner (default since `[email protected]`).
-* Use a test environment class that complies with `jest-metadata` lifecycle.
-* Create or install a reporter that leverages `jest-metadata`.
+* 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 that it doesn't clash with other metadata.
+
+The best live example of how to use `jest-metadata` at the moment is [jest-allure2-reporter].
 
-## 🚀 Installation
+## 🚀 Quick Start
+
+To get your hands dirty, you can try out `jest-metadata` directly in your project.
 
 Install `jest-metadata` using npm:
 
@@ -41,15 +48,15 @@ npm install jest-metadata --save-dev
 In your Jest config, add the following:
 
 ```diff
-   "testRunner": "jest-circus/runner",
 +  "testEnvironment": "jest-metadata/environment-node",
-   "reporters": [
-     "default",
++  "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](jest-environment.md) document.
+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][jest-environment] guide.
 
 ## 📖 Usage
 
@@ -58,7 +65,7 @@ If you need to use `jest-metadata` in a JSDOM environment or another custom test
 Attach metadata to test entities using annotations:
 
 ```js
-import { $Set } from 'jest-metadata';
+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
@@ -70,6 +77,10 @@ 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' },
+    ]);
+    // ...
   });
 });
 ```
@@ -86,10 +97,11 @@ class CustomReporter extends JestMetadataReporter {
   async onTestCaseResult(test, testCaseResult) {
     await super.onTestCaseResult(test, testCaseResult);
 
-    const metadata = state.getRunMetadata(test.path).lastTestEntry;
+    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', ''));
+    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--) {
@@ -104,7 +116,7 @@ class CustomReporter extends JestMetadataReporter {
 
 ## 📄 Documentation
 
-For more detailed documentation, tutorials, and examples, see the [`docs` folder].
+For more detailed documentation and examples, see the [`docs` folder].
 
 ## 🌐 Contributing
 
@@ -120,8 +132,10 @@ For more information, see our [Contribution Guidelines].
 
 This project is licensed under the [MIT License].
 
-[`docs` folder]: ./
+[`docs` folder]: ./docs
 [GitHub issues]: https://github.com/wix-incubator/jest-metadata/issues
-[submit a new issue]: https://github.com/wix-incubator/jest-metadata/issues/new
+[submit a new issue]: https://github.com/wix-incubator/jest-metadata/issues/new/choose
 [Contribution Guidelines]: ./CONTRIBUTING.md
-[MIT License]: ../LICENSE
+[MIT License]: ./LICENSE
+[jest-environment]: ./docs/jest-environment.md
+[jest-allure2-reporter]: https://github.com/wix-incubator/jest-allure2-reporter

docs/state.md

@@ -23,15 +23,13 @@ const { metadata, $Set, $Push } = require('jest-metadata');
 
 const $Description = (text) => $Set('vendor.description', text);
 const $Maintainer = (name, email) => $Assign('vendor.maintainer', { name, email });
-const $Lead = (name, email) => $Merge('vendor.lead', { name, email });
 const $Tag = (value) => $Push(['vendor', 'labels'], value);
 const $Flaky = () => $Tag('flaky');
 const step = (text) => metadata.push('vendor.steps', [{ text, startedAt: now }]);
 
 const actions = require('./actions');
 
 $Maintainer('Jane Smith', '[email protected]');
-$Lead('Samantha Jones', '[email protected]');
 $Description('This is a sample test suite.');
 describe('Login flow', () => {
   $Description('Prepare the environment');

package.json

@@ -5,6 +5,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
+    ".idea/icon.svg",
+    "README.md",
     "src",
     "dist",
     "*.js",

src/environment-decorator.ts

@@ -95,7 +95,7 @@ export function WithMetadata<E extends JestEnvironment>(
 
       async setup() {
         await super.setup();
-        await onTestEnvironmentSetup();
+        await onTestEnvironmentSetup(this);
       }
 
       // @ts-expect-error TS2415: The base class has an arrow function, but this can be a method
@@ -112,7 +112,7 @@ export function WithMetadata<E extends JestEnvironment>(
 
       async teardown() {
         await super.teardown();
-        await onTestEnvironmentTeardown();
+        await onTestEnvironmentTeardown(this);
       }
     },
   }[compositeName] as unknown as new (...args: any[]) => WithEmitter<E>;

src/environment-hooks.ts

@@ -93,13 +93,13 @@ export type ForwardedCircusEvent<E extends Circus.Event = Circus.Event> = {
   state: Circus.State;
 };
 
-export async function onTestEnvironmentSetup(): Promise<void> {
+export async function onTestEnvironmentSetup(_env: JestEnvironment): Promise<void> {
   if (realm.type === 'child_process') {
     await realm.ipc.start();
   }
 }
 
-export async function onTestEnvironmentTeardown(): Promise<void> {
+export async function onTestEnvironmentTeardown(_env: JestEnvironment): Promise<void> {
   if (realm.type === 'child_process') {
     await realm.ipc.stop();
   }