Skip to main content

Descriptions

A well-written description can enhance the usefulness of a test by providing clear context and expected outcomes. Anyone who sees your test for the first time may benefit from a rich description.

There are two ways to define a description for a test:

  • declaratively, via @desc, @description, @descriptionHtml docblocks (or even without them);
  • programmatically, via our DSL – $Description or $DescriptionHtml pseudo-decorators.
Note

Descriptions are not supported on a suite (describe) or test hooks (beforeAll, beforeEach, afterAll, afterEach) level due to limitations of Jest and Allure Framework.

Anyway, we have a few workarounds for you down below. 😉

Test cases​

Allure Framework supports rich text descriptions for tests in Markdown and HTML formats.

To make your experience better, jest-allure2-reporter appends a source code of every test to its description, so you can always get value from this feature.

Note

Docblocks must be inside the test function to work.

test('should add two numbers', () => {
  /**
   * This test demonstrates the `+` operator.
   */
  expect(1 + 2).toBe(3);
});

test('should multiply two numbers', () => {
  /**
   * @description
   * This test demonstrates the `*` operator.
   */
  expect(3 * 2).toBe(6);
});

test('should subtract two numbers', () => {
  /**
   * @descriptionHtml
   * This test demonstrates the <code>-</code> operator.
   */
  expect(2 - 1).toBe(1);
});

Test hooks​

Test hooks such as beforeAll, beforeEach, afterAll, afterEach are treated as steps in Allure Framework. Therefore, they can have only a plain name, but no description.

beforeAll(() => {
  /** This hook runs before all tests. */
});

beforeEach(() => {
  /** This hook runs before each test. */
});

afterEach(() => {
  /** This hook runs after each test. */
});

Test suites​

Allure Framework doesn't treat test suites as separate entities, so the best we can offer is to prepend their descriptions to every test within the suite.

Due to Jest limitations, you can't use docblocks on a suite level, so the only way to add a description is to use our DSL.

import { $Description } from 'jest-allure2-reporter/api';

$Description('The test is operating on `/login` page.')
describe('Sanity: Login flow', () => {
  it('should login with valid credentials', () => {
    /** Testing the transition to the `/dashboard` page. */
    // ...
  });

  it('should login with invalid credentials', () => {
    /** Testing the validation summary component. */
    // ...
  });
});

Test files​

In many cases you may find it acceptable to describe the whole test file, which usually is equal to adding a description to the top-level describe block. More often than not you have a single top-level describe block, so you won't notice the difference:

/**
 * @description
 * The test is operating on `/login` page.
 */
import { $Description } from 'jest-allure2-reporter/api';

describe('Sanity: Login flow', () => {
  it('should login with valid credentials', () => {
    /** Testing the transition to the `/dashboard` page. */
    // ...
  });

  it('should login with invalid credentials', () => {
    /** Testing the validation summary component. */
    // ...
  });
});
Note

You must use @desc or @description pragma due to Jest limitations regarding file-level docblocks.

Configuration​

Description template​

As mentioned before, a test description is a sequence of user-defined paragraphs, followed by a source code of the test itself.

To customize the template, you can use description option in your jest.config.js. Below is a rough example of how you can do it:

/** @type {import('@jest/types').Config.InitialOptions} */
module.exports = {
  testEnvironment: 'jest-allure2-reporter/environment-node',
  reporters: [
    'default',
    [
      'jest-allure2-reporter',
      /** @type {import('jest-allure2-reporter').ReporterOptions} */
      {
        testCase: {
          description: ({ testCaseMetadata }) => [
            ...testCaseMetadata.description,
            '```js',
            ...(testCaseMetadata.code?.beforeAll ?? []),
            ...(testCaseMetadata.code?.beforeEach ?? []),
            ...(testCaseMetadata.code?.test ?? []),
            ...(testCaseMetadata.code?.afterEach ?? []),
            ...(testCaseMetadata.code?.afterAll ?? []),
            '```',
          ].join('\n\n'),
        }
      }
  ],
};

To switch to a HTML template, reset the description customizer to return undefined and use descriptionHtml option instead:

/** @type {import('@jest/types').Config.InitialOptions} */
module.exports = {
  testEnvironment: 'jest-allure2-reporter/environment-node',
  reporters: [
    'default',
    [
      'jest-allure2-reporter',
      /** @type {import('jest-allure2-reporter').ReporterOptions} */
      {
        testCase: {
          description: () => {}, // suppress the default template
          descriptionHtml: ({ testCaseMetadata }) => { /* ... */ },
        }
      }
  ],
};

Markdown support​

By default, jest-allure2-reporter uses remark processor to render Markdown descriptions. It is not possible to customize it right now, but we're working on it.

You'll be able to define your own remark plugins and configure the processor in one of the next releases.