@cerios/playwright-expectly

@cerios/playwright-expectly

Comprehensive Playwright test matchers for strings, numbers, dates, arrays, objects, and locators. Simplify your E2E tests with intuitive assertions.

Features

• 🎯 50+ Custom Matchers - Extensive validation for all data types
• 🔤 String Validation - Email, URL, UUID, alphanumeric, and more
• 🔢 Number Arrays - Sorting, statistics, ranges, and patterns
• 📅 Date Operations - Comparisons, ranges, quarters, and business logic
• 🎨 Locator Assertions - DOM element validation and text formatting
• 📦 Object Arrays - Sorting, uniqueness, and property validation
• 💪 Type-Safe - Full TypeScript support
• ⚡ Zero Dependencies - Only Playwright required

Installation

npm install @cerios/playwright-expectly --save-dev

Quick Start

import { expectly } from '@cerios/playwright-expectly';

// String validation
expectly('[e-mail]').toBeValidEmail();

// Number array validation
expectly([1, 2, 3, 4, 5]).toHaveAscendingOrder();

// Date validation
expectly(new Date()).toBeInTheFuture(new Date('2020-01-01'));

// Locator validation
await expectly(page.locator('.username')).toBeAlphanumeric();

Available Matchers

String Matchers

• toBeValidEmail() - Validate email format
• toBeValidUrl() - Validate URL format
• toBeUUID(version?) - Validate UUID (optionally specific version)
• toBeAlphanumeric() - Only letters and numbers
• toBeNumericString() - Only digits
• toStartWith(prefix) / toEndWith(suffix) - String boundaries
• toMatchPattern(regex) - Regular expression matching

📖 View all string matchers →

Number Array Matchers

• toHaveAscendingOrder() / toHaveDescendingOrder() - Sort validation
• toHaveAverage(value) / toHaveMedian(value) - Statistical validation
• toHaveMin(value) / toHaveMax(value) - Boundary validation
• toBeAllPositive() / toBeAllNegative() - Sign validation
• toBeMonotonic() - Consistent direction
• toHaveConsecutiveIntegers() - Sequential validation

📖 View all number array matchers →

Date Matchers

• toBeCloseTo(date, deviation) - Within time deviation
• toBeInTheFuture(refDate?) / toBeInThePast(refDate?) - Temporal validation
• toBeSameDay(date) / toBeSameMonth(date) / toBeSameYear(date) - Date comparison
• toBeInQuarter(quarter) - Quarter validation
• toBeLeapYear() - Leap year check
• toHaveConsecutiveDates(unit) - Sequential dates

📖 View all date matchers →

Locator Matchers

• toBeAlphanumeric() - Alphanumeric text
• toBeNumericString() - Numeric text
• toBeUUID(version?) - UUID format
• toBeUpperCase() / toBeLowerCase() - Case validation
• toBeTitleCase() - Title case format
• toHaveSrc(value) / toHaveHref(value) / toHaveAlt(value) - Attribute validation

📖 View all locator matchers →

Object Array Matchers

• toHaveObjectsInAscendingOrderBy(property) - Sort by property
• toHaveObjectsInDescendingOrderBy(property) - Reverse sort by property
• toHaveOnlyUniqueObjects() - Uniqueness validation

📖 View all object array matchers →

String Array Matchers

• toHaveAscendingOrder() / toHaveDescendingOrder() - Alphabetical order
• toHaveStrictlyAscendingOrder() - No duplicates ascending
• toBeMonotonic() - Consistent direction
• toHaveUniqueValues() - No duplicates

📖 View all string array matchers →

Generic Matchers

• toBeInteger() / toBeFloat() - Number type validation
• toBeAnyOf(...values) - Multiple value matching
• toEqualPartially(expected) - Partial object matching
• toBeNullish() - Null or undefined check
• toBePrimitive() / toBeArray() / toBeObject() - Type checking

📖 View all generic matchers →

Usage Examples

Basic String Validation

import { expectly } from '@cerios/playwright-expectly';

test('validate user input', async () => {
  expectly('[e-mail]').toBeValidEmail();
  expectly('https://example.com').toBeValidUrl();
  expectly('550e8400-e29b-41d4-a716-446655440000').toBeUUID(4);
});

Number Array Assertions

test('validate sorted data', async () => {
  const scores = [85, 90, 92, 95];

  expectly(scores).toHaveAscendingOrder();
  expectly(scores).toHaveAverage(90.5);
  expectly(scores).toBeAllPositive();
});

Date Comparisons

test('validate dates', async () => {
  const now = new Date();
  const tomorrow = new Date(now.getTime() + 86400000);

  expectly(tomorrow).toBeInTheFuture(now);
  expectly(tomorrow).toBeCloseTo(now, { hours: 24 });
});

DOM Element Validation

test('validate form elements', async ({ page }) => {
  await expectly(page.locator('.email')).toBeValidEmail();
  await expectly(page.locator('.username')).toBeAlphanumeric();
  await expectly(page.locator('img')).toHaveAlt('Company Logo');
});

Advanced Usage

Individual Matcher Imports

For tree-shaking optimization, import only what you need:

import { expectlyString } from '@cerios/playwright-expectly';
import { expectlyNumberArray } from '@cerios/playwright-expectly';
import { expectlyDate } from '@cerios/playwright-expectly';

expectlyString('[e-mail]').toBeValidEmail();
expectlyNumberArray([1, 2, 3]).toHaveAscendingOrder();
expectlyDate(new Date()).toBeInTheFuture(new Date('2020-01-01'));

Negation

All matchers support .not for inverse assertions:

expectly('not-an-email').not.toBeValidEmail();
expectly([5, 3, 1]).not.toHaveAscendingOrder();
await expectly(page.locator('.text')).not.toBeNumericString();

Documentation

• 📖 String Matchers - Email, URL, UUID, alphanumeric validation
• 📖 Number Array Matchers - Sorting, statistics, range checks
• 📖 Date Matchers - Date comparisons, quarters, business days
• 📖 Locator Matchers - DOM element text and attribute validation
• 📖 Object Array Matchers - Sorting and uniqueness by property
• 📖 String Array Matchers - Alphabetical sorting and uniqueness
• 📖 Generic Matchers - Type checking and partial matching
• 📖 API Reference - Complete API documentation

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Cerios

Support

• 📫 Report Issues
• 💬 Discussions
• 🌐 Website

Built with ❤️ by Cerios