Helper Functions

API reference for annotation helper functions.

Generic Helpers

These helpers work with any annotation schema.

pushAnnotations

Push any annotations to a test.


function pushAnnotations<T extends TestAnnotations>(
  testInfo: TestInfo,
  annotations: T
): void

Parameters:

testInfo — Playwright’s TestInfo object (from test callback)
annotations — Object containing annotation key-value pairs

Example:


import { pushAnnotations } from '@lytics/playwright-annotations';
 
test('my test', async ({}, testInfo) => {
  pushAnnotations(testInfo, {
    myField: 'value',
    myOtherField: 'another value',
    tags: ['@smoke', '@critical']
  });
});

getAnnotations

Extract annotations from a test case.


function getAnnotations<T extends TestAnnotations>(
  test: TestCase
): T | null

Parameters:

test — Playwright’s TestCase object

Returns: Annotations object or null if no annotations found

Example:


import { getAnnotations } from '@lytics/playwright-annotations';
 
// In a reporter or post-processing script
const annotations = getAnnotations<MyAnnotations>(test);
if (annotations) {
  console.log(annotations.myField);
}

Contentstack Helpers

Convenience helpers for the Contentstack annotation pattern.

pushSuiteAnnotation

Set the suite annotation (use in beforeEach).


function pushSuiteAnnotation(
  testInfo: TestInfo,
  testSuiteName: string
): void

Parameters:

testInfo — Playwright’s TestInfo object
testSuiteName — The test suite name (e.g., "ACCOUNT_SECURITY")

Example:


import { pushSuiteAnnotation } from '@lytics/playwright-annotations';
 
test.describe('Account Security', () => {
  test.beforeEach(async ({}, testInfo) => {
    pushSuiteAnnotation(testInfo, 'ACCOUNT_SECURITY');
  });
 
  // All tests in this describe block will have testSuiteName: "ACCOUNT_SECURITY"
});

Call pushSuiteAnnotation in beforeEach so all tests in the describe block inherit the suite annotation.

pushTestAnnotations

Set test annotations with validation.


function pushTestAnnotations(
  testInfo: TestInfo,
  annotations: { journeyId: string; testCaseId: string }
): void

Parameters:

testInfo — Playwright’s TestInfo object
annotations.journeyId — The journey ID
annotations.testCaseId — The test case ID (must be unique)

Example:


import { pushTestAnnotations } from '@lytics/playwright-annotations';
 
test('user can view tokens', async ({}, testInfo) => {
  pushTestAnnotations(testInfo, {
    journeyId: 'ACCOUNT_SECURITY_VIEW-TOKENS',
    testCaseId: 'ACCOUNT_SECURITY_VIEW-TOKENS_VALID',
  });
 
  // Test implementation...
});

pushContentstackAnnotations

Set all Contentstack annotations at once.


function pushContentstackAnnotations(
  testInfo: TestInfo,
  annotations: ContentstackAnnotations
): void

Parameters:

testInfo — Playwright’s TestInfo object
annotations — Full ContentstackAnnotations object

Example:


import { pushContentstackAnnotations } from '@lytics/playwright-annotations';
 
test('my test', async ({}, testInfo) => {
  pushContentstackAnnotations(testInfo, {
    testSuiteName: 'ACCOUNT_SECURITY',
    journeyId: 'ACCOUNT_SECURITY_VIEW-TOKENS',
    testCaseId: 'ACCOUNT_SECURITY_VIEW-TOKENS_VALID',
    tags: ['@smoke'],
  });
});

When using pushContentstackAnnotations, you must provide all required fields. For most cases, using pushSuiteAnnotation in beforeEach + pushTestAnnotations in each test is cleaner.

getContentstackAnnotations

Extract Contentstack annotations from a test.


function getContentstackAnnotations(
  test: TestCase
): ContentstackAnnotations | null

Parameters:

test — Playwright’s TestCase object

Returns: ContentstackAnnotations object or null if annotations are incomplete

Example:


import { getContentstackAnnotations } from '@lytics/playwright-annotations';
 
// In a reporter
const annotations = getContentstackAnnotations(test);
if (annotations) {
  console.log(`Suite: ${annotations.testSuiteName}`);
  console.log(`Journey: ${annotations.journeyId}`);
  console.log(`Test Case: ${annotations.testCaseId}`);
}

Usage Patterns

Standard Pattern

The recommended pattern for Contentstack teams:


import { test } from '@playwright/test';
import { pushSuiteAnnotation, pushTestAnnotations } from '@lytics/playwright-annotations';
 
test.describe('User Management @smoke', () => {
  // Set suite annotation once for all tests
  test.beforeEach(async ({}, testInfo) => {
    pushSuiteAnnotation(testInfo, 'USER_MANAGEMENT');
  });
 
  test('admin can create user', async ({}, testInfo) => {
    pushTestAnnotations(testInfo, {
      journeyId: 'USER_MANAGEMENT_CREATE-USER',
      testCaseId: 'USER_MANAGEMENT_CREATE-USER_VALID',
    });
    // Test implementation...
  });
 
  test('validates required fields', async ({}, testInfo) => {
    pushTestAnnotations(testInfo, {
      journeyId: 'USER_MANAGEMENT_CREATE-USER',
      testCaseId: 'USER_MANAGEMENT_CREATE-USER_INVALID',
    });
    // Test implementation...
  });
});

Multiple Journeys in One File

When a test file covers multiple journeys:


test.describe('Account Settings', () => {
  test.beforeEach(async ({}, testInfo) => {
    pushSuiteAnnotation(testInfo, 'ACCOUNT_SETTINGS');
  });
 
  test.describe('Profile', () => {
    test('can update name', async ({}, testInfo) => {
      pushTestAnnotations(testInfo, {
        journeyId: 'ACCOUNT_SETTINGS_PROFILE',
        testCaseId: 'ACCOUNT_SETTINGS_PROFILE_UPDATE-NAME',
      });
    });
  });
 
  test.describe('Security', () => {
    test('can change password', async ({}, testInfo) => {
      pushTestAnnotations(testInfo, {
        journeyId: 'ACCOUNT_SETTINGS_SECURITY',
        testCaseId: 'ACCOUNT_SETTINGS_SECURITY_CHANGE-PASSWORD',
      });
    });
  });
});

Custom Schema with Generic Helpers


import { pushAnnotations } from '@lytics/playwright-annotations';
 
interface MyAnnotations {
  epic: string;
  story: string;
  severity: 'blocker' | 'critical' | 'major' | 'minor';
}
 
test('my test', async ({}, testInfo) => {
  pushAnnotations<MyAnnotations>(testInfo, {
    epic: 'AUTH-2023',
    story: 'AUTH-2023-01',
    severity: 'critical',
  });
});

Debug Mode

Enable verbose logging to troubleshoot annotation issues:


PLAYWRIGHT_ANNOTATIONS_DEBUG=true npx playwright test

When enabled, all helper functions log detailed information:


🔍 [playwright-annotations] pushSuiteAnnotation called {
  "testTitle": "user can view access tokens",
  "testSuiteName": "ACCOUNT_SECURITY",
  "existingAnnotations": []
}
🔍 [playwright-annotations] pushSuiteAnnotation complete {
  "finalAnnotations": [{ "type": "testSuiteName", "description": "ACCOUNT_SECURITY" }]
}

This helps diagnose:

Whether beforeEach is running before your test
What annotations exist at each step
Validation errors and their causes