- operator.
+ */
+test('should subtract two numbers', () => {
+ expect(2 - 1).toBe(1);
+});
+```
+
+## `@displayName`
+
+Overrides test names specified in `test('...')` or `it('...')` in the test report.
+
+```javascript
+/**
+ * @displayName 1 + 1 = 2
+ */
+test('First test', () => {
+ expect(1 + 1).toBe(2);
+});
+```
+
+When applied to a hook, it sets a custom display name for the hook, similar to a [plain comment](#plain-comments):
+
+```javascript
+/**
+ * @displayName Custom "beforeEach" hook
+ */
+beforeEach(() => {
+ // Hook implementation
+});
+```
+
+## `@fullName`
+
+Sets a full name for a test case, which can be used for more detailed identification.
+By default, full names are also used for tracking test history across multiple runs or retries.
+
+```javascript
+/**
+ * @fullName Arithmetic > Addition > Valid assertion
+ */
+test('First test', () => {
+ expect(1 + 1).toBe(2);
+});
+```
+
+## `@historyId`
+
+Assigns a custom history ID to a test case, useful for tracking test history across multiple runs or retries.
+
+```javascript
+/**
+ * @historyId HISTORY-2
+ */
+test('First test', () => {
+ expect(2 + 2).toBe(3);
+});
+```
+
+## `@issue`
+
+Links an issue to a test case.
+
+```javascript
+/**
+ * @issue XMLRPC-15
+ */
+test('Proving the fix', () => {
+ expect(1 + 1).toBe(2);
+});
+```
+
+## `@owner`
+
+Specifies the owner of a test or suite.
+
+```javascript
+/**
+ * @owner John Doe
+ */
+describe('Suite maintained by John', () => {
+ test('First test', () => {
+ // Test implementation
+ });
+});
+```
+
+## `@package`
+
+Specifies the package for a test or suite, useful for organizing tests.
+
+```javascript
+/**
+ * @package e2e.pragmas
+ */
+describe('My service', () => {
+ /**
+ * @testMethod Alternative title for the test
+ */
+ test('should log a message', () => {
+ // Test implementation
+ });
+});
+```
+
+## `@severity`
+
+Sets the severity level for a test or suite.
+
+```javascript
+/**
+ * @severity critical
+ */
+describe('Test suite', () => {
+ test('Important test 1', () => {
+ expect(1 + 1).toBe(2);
+ });
+});
+```
+
+## `@epic`, `@feature`, `@story`
+
+Categorizes tests into epics and features for better organization.
+
+```javascript
+/**
+ * @epic Arithmetic operations
+ * @feature Addition
+ * @story Sane assumptions
+ */
+describe('Test suite', () => {
+ // Test cases
+});
+```
+
+## `@tag`
+
+Adds tags to a test or suite.
+
+```javascript
+/**
+ * @tag docblock, arithmetic
+ */
+describe('Test suite', () => {
+ /**
+ * @tag addition
+ */
+ test('First test', () => {
+ expect(1 + 1).toBe(2);
+ });
+});
+```
+
+## `@thread`
+
+Specifies a custom thread for concurrent tests.
+Do not use it unless you want to control tests on the [Timeline](#TODO) manually.
+
+```javascript
+/**
+ * @thread IV
+ */
+test('First test', () => {
+ expect(1 + 1).toBe(2);
+});
+```
+
+## `@tms`
+
+Links a test management system (TMS) case to a test.
+
+```javascript
+/**
+ * @tms TMS-1234
+ */
+test('should be linked to a TMS ticket', () => {
+ expect(1 + 1).toBe(2);
+});
+```
+
+## `@url`
+
+Adds a custom URL link to a test or suite.
+
+```javascript
+/**
+ * @url https://en.wikipedia.org/wiki/Arithmetic 🔢 Arithmetic
+ */
+describe('Arithmetics', () => {
+ /**
+ * @url https://en.wikipedia.org/wiki/Addition ➕ Addition
+ */
+ test('1 + 1 = 2', () => {
+ expect(1 + 1).toBe(2);
+ });
+});
+```
+
+## `@parentSuite`, `@suite`, `@subSuite`
+
+Organizes tests into a hierarchical suite structure.
+
+```javascript
+/**
+ * @parentSuite Custom Parent Suite
+ * @suite Custom Suite
+ * @subSuite Custom Sub-Suite
+ */
+test('Test outside of any suite', () => {
+ // Test implementation
+});
+```
+
+These docblock annotations provide a powerful way to enrich your tests with metadata, improving the organization and readability of your Allure reports. By using these annotations, you can create more informative and structured test reports that help in better understanding and maintaining your test suite.
diff --git a/docs/api/02-annotations.mdx b/docs/api/02-annotations.mdx
new file mode 100644
index 00000000..8aee65af
--- /dev/null
+++ b/docs/api/02-annotations.mdx
@@ -0,0 +1,354 @@
+---
+sidebar_position: 3
+---
+
+# Annotations
+
+Annotations are functions that can be called before test suites or tests to add metadata to them. They share the same purpose as [docblocks](./01-docblocks.mdx), but they execute at runtime, allowing you to add metadata dynamically. Annotations can also be used to bypass the limitation of docblocks not being applicable to `describe` statements.
+
+To use annotations, you'll need to import them first, e.g.:
+
+```typescript
+import { $Description, $Link, $Owner } from 'jest-allure2-reporter/api';
+```
+
+Alternatively, you can [configure `jest-allure2-reporter/globals`](#TODO) to make them available globally.
+
+## `$Description`
+
+Adds a Markdown description to a test or suite.
+
+```javascript
+$Description('### Suite-level description')
+describe('Test suite', () => {
+ $Description('Demonstrates a **passing** test case')
+ test('First test', () => {
+ expect(1 + 1).toBe(2);
+ });
+
+ $Description('Demonstrates a **failing** test case')
+ test('Second test', () => {
+ expect(2 + 2).toBe(3);
+ });
+});
+```
+
+## `$DescriptionHtml`
+
+Adds an HTML description to a test or suite.
+
+```javascript
+$DescriptionHtml('This test verifies the login functionality.
'); +``` + +### `allure.epic(string)` + +Sets the epic for the current test case. + +```javascript +allure.epic('User Authentication'); +``` + +### `allure.feature(string)` + +Sets the feature for the current test case. + +```javascript +allure.feature('Login'); +``` + +### `allure.story(string)` + +Sets the user story for the current test case. + +```javascript +allure.story('User can log in with valid credentials'); +``` + +### `allure.suite(string)` + +Sets the suite name for the current test case. + +```javascript +allure.suite('Authentication Tests'); +``` + +### `allure.label(name, string)` + +Adds a custom label to the current test case. + +```javascript +allure.label('custom', 'value'); +``` + +### `allure.parameter(name, value)` + +Adds a parameter to the current test case or step. + +```javascript +allure.parameter('username', 'testuser'); +``` + +## Link Methods + +### `allure.link(url[, name])` + +Adds a link to the current test case. + +```javascript +allure.link('https://example.com', 'Example Link'); +``` + +### `allure.issue(name[, url])` + +Adds an issue link to the current test case. + +```javascript +allure.issue('JIRA-123'); +``` + +### `allure.tms(name[, url])` + +Adds a Test Management System (TMS) link to the current test case. + +```javascript +allure.tms('TMS-456'); +``` + +## Status Methods + +### `allure.status(status)` + +Sets the status for the current test case or step. + +```javascript +allure.status('failed'); +``` + +### `allure.statusDetails({ message, trace })` + +Sets additional status details for the current test case or step. + +```javascript +allure.statusDetails({ message: 'Test failed due to...', trace: 'Error stack trace' }); +``` + +## Attachments + +### `allure.attachment(string, content[, type])` + +Adds an attachment to the current test case or step. + +```javascript +allure.attachment('Screenshot', Buffer.from('...'), 'image/png'); +``` + +### `allure.createAttachment(name: string, content: () => string | Buffer, type?: string)` + +Creates a reusable attachment function. + +```javascript +const takeScreenshot = allure.createAttachment('Screenshot', () => Buffer.from('...'), 'image/png'); +takeScreenshot(); +``` + +## Steps + +### `allure.step(name, fn)` + +Adds a step to the current test case. + +```javascript +allure.step('Enter username', () => { + // Step implementation +}); +``` + +### `allure.createStep(name, fn)` + +Creates a reusable step function. + +```javascript +const login = allure.createStep('Login', (username, password) => { + // Login implementation +}); +login('testuser', 'password123'); +``` + +## Advanced Methods + +### `allure.$bind(options)` + +Binds an instance of the Allure Runtime API to a specific time and context in your test code. + +```javascript +const boundAllure = allure.$bind({ metadata: true, time: false }); +``` + +Use it when you need to report some metadata post-factum, e.g. add some information about +the test after leaving its body, e.g.: + +```javascript +let allure$; + +test('...', () => { + allure$ = allure.$bind(); + // ... +}); + +afterEach(() => { + allure$.parameter('Free Memory', os.freemem()); +}); +``` + +### `allure.$plug(callback)` + +Registers a runtime plugin to extend Allure functionality. + +```javascript +allure.$plug((context) => { + // Plugin implementation +}); +``` + +Read more about [plugins](#TODO). diff --git a/docs/api/05-plugin-api.mdx b/docs/api/05-plugin-api.mdx new file mode 100644 index 00000000..3587c12a --- /dev/null +++ b/docs/api/05-plugin-api.mdx @@ -0,0 +1,159 @@ +--- +sidebar_position: 7 +--- + +# Plugin API + +The Plugin API in `jest-allure2-reporter` allows you to extend and customize the functionality of Allure reporting. This powerful feature enables you to add custom behaviors, modify existing ones, or integrate with other tools and services. + +## Overview + +Plugins are registered using the `allure.$plug()` method, which takes a callback function as its argument. This callback receives a context object that provides access to various aspects of the Allure runtime. + +```javascript +import { allure } from 'jest-allure2-reporter/api'; + +allure.$plug((context) => { + // Plugin implementation +}); +``` + +## Plugin Context + +The plugin context (`AllureRuntimePluginContext`) provides the following properties and methods: + +### `runtime` + +Type: `IAllureRuntime` + +Gives access to the [Allure runtime](./04-runtime-api.mdx), allowing you to interact with the core Allure functionality. + +### `handlebars` + +Type: `HandlebarsAPI` + +Provides access to the Handlebars templating engine, which can be useful for generating custom content. + +### `contentAttachmentHandlers` + +Type: `Recordjest-allure2-reporterjest-allure2-reporter/api$Link, $Owner.allure.step, allure.attachment.jest-allure2-reporter/globalsjest-allure2-reporter/environment-nodejest-allure2-reporter/environment-jsdomjest-allure2-reporter/environment-decoratorjest-allure2-reporterjest-allure2-reporter/api$Link, $Owner.allure.step, allure.attachment.jest-allure2-reporter/environment-nodejest-allure2-reporter/environment-jsdomjest-allure2-reporter/environment-decoratorbeta version of the reporter can be seen on npm registry.
-
+ jest-allure2-reporter{' '}