vineguard-e2e-runner

E2E test runner with Page Object Model and MSW integration for Playwright and Cypress

Features

🎭 E2E Test Execution

• Playwright Runner: Execute Playwright tests with full browser support (Chromium, Firefox, WebKit)
• Cypress Runner: Execute Cypress tests with interactive and headless modes
• Debug Context: Capture console logs, network requests, and performance metrics

📄 Page Object Model (POM) Support (v1.1.0)

• Auto-Discovery: Automatically discover and load Page Object Models
• Playwright POMs: Dynamic loading with async/await patterns
• Cypress POMs: Singleton pattern with fluent API support
• Fixture Generation: Create test fixtures with pre-loaded POMs

🎯 MSW Integration (v1.1.0)

• Handler Loading: Load MSW handlers for API mocking
• Node & Browser: Support both Jest (Node) and Cypress/Playwright (browser) modes
• Runtime Overrides: Add test-specific handler overrides
• Auto-Setup: Generate MSW setup files for Jest and Playwright

📦 Artifact Loading (v1.1.0)

• Harvest-Planner Integration: Load artifacts exported by VineGuard Harvest-Planner
• Auto-Discovery: Find POMs, MSW handlers, test files, and fixtures
• Framework-Specific: Get artifacts tailored to your test framework
• Validation: Validate artifact structure and completeness

Installation

npm install vineguard-e2e-runner
# or
pnpm add vineguard-e2e-runner
# or
yarn add vineguard-e2e-runner

Optional Peer Dependencies

# For MSW support
npm install msw@^2.0.0

# For Playwright
npm install @playwright/test

# For Cypress
npm install cypress

Quick Start

Basic Playwright Test Execution

import { PlaywrightRunner } from 'vineguard-e2e-runner';

const runner = new PlaywrightRunner('/path/to/project');

const result = await runner.run({
  projectRoot: '/path/to/project',
  framework: 'playwright',
  headless: true,
  browsers: ['chromium', 'firefox']
});

console.log(`Tests: ${result.tests.length}, Failures: ${result.failures.length}`);

Run with Page Object Models

import { runWithPOM } from 'vineguard-e2e-runner';

const result = await runWithPOM({
  projectRoot: '/path/to/project',
  framework: 'playwright',
  pomDirectory: '/path/to/poms',
  baseUrl: 'http://localhost:3000',
  headless: true
});

// POMs are automatically loaded and available in tests

Run with MSW API Mocking

import { runWithMSW } from 'vineguard-e2e-runner';

const result = await runWithMSW({
  projectRoot: '/path/to/project',
  framework: 'playwright',
  handlersDirectory: '/path/to/msw/handlers',
  serverMode: 'browser',
  onUnhandledRequest: 'warn',
  headless: true
});

// MSW is automatically started before tests and stopped after

Run with VineGuard Artifacts

import { runWithArtifacts } from 'vineguard-e2e-runner';

const result = await runWithArtifacts({
  projectRoot: '/path/to/project',
  framework: 'playwright',
  artifactsDirectory: '/path/to/vineguard-tests',
  usePOM: true,
  useMSW: true,
  headless: true
});

// Automatically discovers and loads POMs, MSW handlers, and test files

API Reference

PlaywrightRunner

Execute Playwright tests with full configuration support.

const runner = new PlaywrightRunner(projectRoot, config);

// Run tests
await runner.run(options);

// Run with debug context capture
await runner.runWithDebugCapture(options);

// Generate Playwright config
await runner.generateConfig(outputPath);

// Install browsers
await runner.installBrowsers();

CypressRunner

Execute Cypress tests with interactive and headless modes.

const runner = new CypressRunner(projectRoot, config);

// Run tests
await runner.run(options);

// Run interactive mode
await runner.runInteractive(options);

// Run with debug context capture
await runner.runWithDebugCapture(options);

// Generate Cypress config
await runner.generateConfig(outputPath);

// Verify Cypress installation
await runner.verify();

PlaywrightPOMRunner

Load and manage Playwright Page Object Models.

import { PlaywrightPOMRunner } from 'vineguard-e2e-runner';
import { Page } from '@playwright/test';

const pomRunner = new PlaywrightPOMRunner({
  pomDirectory: '/path/to/poms',
  baseUrl: 'http://localhost:3000',
  autoLoad: true
});

// Load specific POM
const loginPage = await pomRunner.loadPOM('Login', page);
await loginPage.visit();
await loginPage.login('[email protected]', 'password');

// Load all POMs
const allPOMs = await pomRunner.loadAllPOMs(page);

// Create test fixture
const poms = await pomRunner.createPOMFixture(page);

// Get available POMs
const available = pomRunner.getAvailablePOMs();

CypressPOMRunner

Load and manage Cypress Page Object Models with fluent API.

import { CypressPOMRunner } from 'vineguard-e2e-runner';

const pomRunner = new CypressPOMRunner({
  pomDirectory: '/path/to/cypress/page-objects',
  baseUrl: 'http://localhost:3000',
  autoLoad: true
});

// Load specific POM (singleton pattern)
const homePage = await pomRunner.loadPOM('Home');
homePage.visit().assertHeadingVisible().clickCtaButton();

// Generate POM support file for Cypress
const supportCode = pomRunner.generatePOMSupportFile('/path/to/cypress/support/pom.ts');

// Use in Cypress tests
cy.po('Home').visit().assertHeadingVisible();

MSWHandlerLoader

Load and manage Mock Service Worker handlers.

import { MSWHandlerLoader } from 'vineguard-e2e-runner';

const mswLoader = new MSWHandlerLoader({
  handlersDirectory: '/path/to/handlers',
  serverMode: 'node', // or 'browser'
  autoStart: true,
  onUnhandledRequest: 'warn'
});

// Setup MSW
await mswLoader.setup();

// Add runtime handler overrides
mswLoader.useHandlers(
  http.get('/api/override', () => HttpResponse.json({ custom: true }))
);

// Reset handlers to initial state
mswLoader.resetHandlers();

// Stop MSW
await mswLoader.stop();

// Generate setup files
const jestSetup = mswLoader.generateJestSetup('/path/to/setupTests.ts');
const playwrightSetup = mswLoader.generatePlaywrightSetup('/path/to/msw-setup.ts');

ArtifactLoader

Discover and load test artifacts from Harvest-Planner exports.

import { ArtifactLoader } from 'vineguard-e2e-runner';

const artifactLoader = new ArtifactLoader({
  projectRoot: '/path/to/project',
  artifactsDirectory: '/path/to/vineguard-tests',
  autoDiscover: true,
  framework: 'playwright'
});

// Get all artifacts
const artifacts = artifactLoader.getArtifacts();

// Get structured artifacts
const structure = artifactLoader.getArtifactStructure();

// Get framework-specific artifacts
const playwrightArtifacts = artifactLoader.getFrameworkArtifacts('playwright');

// Get artifact counts
const counts = artifactLoader.getArtifactCount();

// Validate structure
const validation = artifactLoader.validateStructure();

// Refresh discovery
artifactLoader.refresh();

Usage Examples

Example 1: Playwright with POMs and MSW

import { PlaywrightRunner, PlaywrightPOMRunner, MSWHandlerLoader } from 'vineguard-e2e-runner';
import { test } from '@playwright/test';

// Setup POMs
const pomRunner = new PlaywrightPOMRunner({
  pomDirectory: './e2e/page-objects',
  baseUrl: 'http://localhost:3000'
});

// Setup MSW
const mswLoader = new MSWHandlerLoader({
  handlersDirectory: './e2e/mocks',
  serverMode: 'browser'
});

await mswLoader.setup();

// Run tests
const runner = new PlaywrightRunner('./');
const result = await runner.run({
  projectRoot: './',
  framework: 'playwright',
  headless: true
});

await mswLoader.stop();

Example 2: Cypress with Fluent API POMs

import { CypressPOMRunner } from 'vineguard-e2e-runner';

const pomRunner = new CypressPOMRunner({
  pomDirectory: './cypress/page-objects',
  baseUrl: 'http://localhost:3000'
});

// Generate support file
pomRunner.generatePOMSupportFile('./cypress/support/pom.ts');

// In Cypress tests
describe('User Journey', () => {
  it('should complete checkout', () => {
    cy.po('Home')
      .visit()
      .clickProduct()
      .then(() => {
        cy.po('Product')
          .addToCart()
          .goToCheckout();
      })
      .then(() => {
        cy.po('Checkout')
          .fillShippingInfo({ name: 'John Doe', address: '123 Main St' })
          .submitOrder()
          .assertSuccess();
      });
  });
});

Example 3: Using VineGuard Artifacts

import { runWithArtifacts } from 'vineguard-e2e-runner';

// VineGuard Harvest-Planner exports test artifacts to vineguard-tests/
const result = await runWithArtifacts({
  projectRoot: './',
  framework: 'playwright',
  artifactsDirectory: './vineguard-tests',
  usePOM: true,
  useMSW: true,
  headless: true,
  browsers: ['chromium']
});

console.log(`
  Total Tests: ${result.tests.length}
  Passed: ${result.tests.filter(t => t.status === 'passed').length}
  Failed: ${result.failures.length}
  Duration: ${result.duration}ms
`);

Configuration

VineGuard Config File

Create vineguard.config.js or vineguard.config.ts in your project root:

export default {
  e2eRunner: {
    framework: 'playwright',
    baseUrl: 'http://localhost:3000',
    headless: true,
    browsers: ['chromium', 'firefox'],
    timeout: 30000,
    retries: 2,
    parallel: true,
    video: true,
    screenshots: true,
    trace: 'on-first-retry'
  },
  pom: {
    directory: './e2e/page-objects',
    autoLoad: true
  },
  msw: {
    handlersDirectory: './e2e/mocks',
    serverMode: 'browser',
    onUnhandledRequest: 'warn'
  },
  artifacts: {
    directory: './vineguard-tests',
    usePOM: true,
    useMSW: true
  }
};

Type Definitions

All types are fully exported for TypeScript users:

import type {
  E2ERunnerOptions,
  E2ETestResult,
  PlaywrightConfig,
  CypressConfig,
  POMConfig,
  CypressPOMConfig,
  MSWConfig,
  ArtifactConfig,
  TestArtifacts,
  ArtifactStructure
} from 'vineguard-e2e-runner';

Best Practices

Page Object Models

1. Use data-testid: Prefer data-testid attributes for reliable element selection
2. Keep POMs focused: One page = one Page Object
3. Separate concerns: Locators, actions, and assertions should be separate
4. Async patterns: Always use async/await for Playwright POMs

MSW Integration

1. Test all scenarios: Success, validation errors, auth failures, server errors
2. Reset handlers: Always reset between tests with mswLoader.resetHandlers()
3. Use overrides: Override specific handlers per test using mswLoader.useHandlers()
4. Network-level mocking: MSW mocks at the network level, works with any HTTP client

Artifact Organization

1. Follow conventions: Use standard directory names (poms/, msw/, tests/)
2. Framework separation: Separate Playwright and Cypress artifacts
3. README files: Include README.md with setup instructions in artifact directory
4. Version artifacts: Tag artifact exports with version/date for tracking

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

MIT © Ian Dave Divinagracia

Links

• GitHub Repository
• npm Package
• VineGuard Main Package
• Issue Tracker

Version History

v1.1.0 (2025-10-13)

• ✨ Added Page Object Model execution support for Playwright and Cypress
• ✨ Added MSW handler loading and integration (Node and browser modes)
• ✨ Added test artifact discovery and loading from Harvest-Planner
• ✨ Added high-level API: runWithPOM(), runWithMSW(), runWithArtifacts()
• ✨ Added POM auto-discovery and dynamic loading
• ✨ Added MSW setup file generation for Jest and Playwright
• ✨ Added comprehensive artifact structure validation
• 🔧 Updated dependencies: Playwright ^1.45.0, Cypress ^13.15.0
• 🔧 Added vineguard-test-cultivator ^2.1.0 integration

v1.0.1

• Initial release with Playwright and Cypress runners
• Debug context collection
• Config generation