Schema & Types

Type definitions for annotations.

Generic Types

TestAnnotations

The base interface that any team can extend:


interface TestAnnotations {
  [key: string]: string | string[] | undefined;
}

This flexible interface allows any string key with string, string array, or undefined values. Extend it to create your own schema:


interface MyTeamAnnotations extends TestAnnotations {
  featureArea: string;
  ticketId: string;
  priority: 'high' | 'medium' | 'low';
}

Contentstack Types

ContentstackAnnotations

The annotation schema used by Contentstack teams:


interface ContentstackAnnotations extends TestAnnotations {
  /**
   * Test Suite: Organizational grouping (product/feature area)
   * Scope: Multiple journeys share one testSuiteName
   * Set in: beforeEach at describe level
   */
  testSuiteName: string;
 
  /**
   * Journey ID: Unique identifier for a user journey
   * Scope: One journey = one test file
   * Format: Typically {testSuiteName}_{JOURNEY-NAME}
   * Set in: Each test() function
   */
  journeyId: string;
 
  /**
   * Test Case ID: Unique identifier for a test scenario
   * Scope: One test case = one test() block
   * Format: {journeyId}_{SCENARIO}
   * Set in: Each test() function (unique per test)
   */
  testCaseId: string;
 
  /**
   * Optional: Tags for test categorization
   */
  tags?: string[];
}

Hierarchy Relationship


testSuiteName (1:N) → journeyId (1:N) → testCaseId

ACCOUNT_SECURITY
  ├── ACCOUNT_SECURITY_VIEW-TOKENS
  │   ├── ACCOUNT_SECURITY_VIEW-TOKENS_VALID
  │   └── ACCOUNT_SECURITY_VIEW-TOKENS_EMPTY
  └── ACCOUNT_SECURITY_CREATE-TOKEN
      └── ACCOUNT_SECURITY_CREATE-TOKEN_VALID

Field Details

testSuiteName

Property	Value
Scope	Multiple journeys share one testSuiteName
Set in	`beforeEach` at describe level
Examples	`"ACCOUNT_SECURITY"`, `"USER_MANAGEMENT"`, `"DATA_PIPELINES"`


test.beforeEach(async ({}, testInfo) => {
  pushSuiteAnnotation(testInfo, 'ACCOUNT_SECURITY');
});

journeyId

Property	Value
Scope	One journey = one test file
Format	Typically `{testSuiteName}_{JOURNEY-NAME}`
Set in	Each `test()` function (same for all tests in journey)
Examples	`"ACCOUNT_SECURITY_VIEW-TOKENS"`, `"USER_MANAGEMENT_CREATE-USER"`

testCaseId

Property	Value
Scope	One test case = one `test()` block
Format	`{journeyId}_{SCENARIO}`
Set in	Each `test()` function (unique per test)
Examples	`"ACCOUNT_SECURITY_VIEW-TOKENS_VALID"`, `"ACCOUNT_SECURITY_VIEW-TOKENS_EMPTY"`

Test Case IDs must be globally unique and stable. They’re used for trend analysis and tracking test history over time.

Validation Result Types

ValidationResult

Returned by validators:


interface ValidationResult {
  /** Whether validation passed (no errors) */
  valid: boolean;
  
  /** Error messages (validation failures) */
  errors: string[];
  
  /** Warning messages (non-blocking issues) */
  warnings: string[];
}

ValidationRule

A function that validates annotations:


type ValidationRule<T extends TestAnnotations> = (
  annotations: T
) => ValidationResult;

ValidatorConfig

Configuration for creating validators:


interface ValidatorConfig<T extends TestAnnotations> {
  rules: ValidationRule<T>[];
}

TestInfo Type

Re-exported from Playwright for convenience:


import type { TestInfo } from '@lytics/playwright-annotations';
 
// Equivalent to:
import type { TestInfo } from '@playwright/test';

Examples

Extending ContentstackAnnotations


import type { ContentstackAnnotations } from '@lytics/playwright-annotations';
 
interface ExtendedAnnotations extends ContentstackAnnotations {
  // Add custom fields
  jiraTicket?: string;
  severity: 'critical' | 'major' | 'minor';
}

Creating a Custom Schema


import type { TestAnnotations } from '@lytics/playwright-annotations';
 
interface MyCompanyAnnotations extends TestAnnotations {
  // Required fields
  component: string;
  feature: string;
  scenario: string;
  
  // Optional fields
  linkedIssue?: string;
  owner?: string;
}