JSPM

vineguard-test-cultivator

2.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 16
  • Score
    100M100P100Q61362F
  • License MIT

VineGuard Test Generator - Creates comprehensive test code with MSW API mocking and Page Object Model patterns for Jest, Playwright, and Cypress

Package Exports

  • vineguard-test-cultivator

Readme

vineguard-test-cultivator

Production-ready test code generation with MSW API mocking and Page Object Model patterns

Generate comprehensive test suites for Jest, Playwright, and Cypress with built-in support for Mock Service Worker (MSW) and Page Object Model (POM) best practices.

npm version License: MIT

Features

🎯 MSW Integration (v2.1.0)

  • Automatic API Mocking: Generate MSW handlers for API routes
  • Error Scenarios: Built-in support for 400, 401, 404, 500 error testing
  • Component Testing: React Testing Library + MSW integration
  • Network-Level Mocking: Realistic API testing with any HTTP client

📄 Page Object Model (v2.1.0)

  • Playwright POM: BasePage + page-specific classes with TypeScript
  • Cypress POM: Fluent API with method chaining and singleton pattern
  • Custom Commands: 13 reusable Cypress commands with type safety
  • Best Practices: Reliable locators, separation of concerns, maintainable tests

🛠️ Test Generation

  • Jest/RTL: Unit, integration, and accessibility tests
  • Playwright: E2E, API, visual, mobile, performance tests
  • Cypress: User flows, API, smoke, visual, accessibility tests
  • Component Testing: Props, state, events, hooks, accessibility

Installation

npm install vineguard-test-cultivator
# or
pnpm add vineguard-test-cultivator
# or
yarn add vineguard-test-cultivator

Quick Start

Generate Jest Tests with MSW

import { JestGenerator, generateTestSuiteWithMSW } from 'vineguard-test-cultivator';

// Generate MSW handlers for API routes
const routes = [
  { path: '/api/users', method: 'GET' },
  { path: '/api/users/:id', method: 'GET' },
  { path: '/api/users', method: 'POST' }
];

const handlers = JestGenerator.generateMSWHandlers(routes);
const setup = JestGenerator.generateMSWSetup();

// Or use high-level API
const testSuite = generateTestSuiteWithMSW(routes, {
  includeErrorScenarios: true,
  includeValidation: true
});

console.log(testSuite.handlers); // MSW handlers code
console.log(testSuite.setup.server); // server.ts code
console.log(testSuite.setup.setupTests); // setupTests.ts code

Generate Component Test with MSW

import { JestGenerator } from 'vineguard-test-cultivator';

const componentTest = JestGenerator.generateComponentTestWithMSW({
  componentName: 'UserList',
  filePath: 'src/components/UserList.tsx',
  testType: 'integration',
  isComponent: true,
  isReact: true,
  apiEndpoint: '/api/users',
  apiMethod: 'GET'
});

// Generates test with:
// - Loading state testing
// - Success scenario with MSW
// - Error handling (500, 401, 404)
// - Retry logic
// - Empty state handling

Generate Playwright Tests with POM

import { PlaywrightGenerator, generateE2ETestsWithPOM } from 'vineguard-test-cultivator';

// Generate BasePage with common utilities
const basePage = PlaywrightGenerator.generateBasePage();

// Generate page-specific POM
const loginPage = PlaywrightGenerator.generatePageObject({
  pageName: 'Login',
  route: '/login',
  elements: [
    { name: 'emailInput', selector: '[data-testid="email"]', type: 'input' },
    { name: 'passwordInput', selector: '[data-testid="password"]', type: 'input' },
    { name: 'submitButton', selector: '[data-testid="submit"]', type: 'button' }
  ]
});

// Or generate from user flows
const userFlows = [
  {
    name: 'User Login Flow',
    steps: [
      { route: '/login', action: 'visit', selector: 'h1' },
      { route: '/login', action: 'fill', selector: '[data-testid="email"]' },
      { route: '/dashboard', action: 'navigate' }
    ]
  }
];

const pageObjects = PlaywrightGenerator.generatePageObjectsFromFlows(userFlows);
// Returns: { BasePage: '...', LoginPage: '...', DashboardPage: '...' }

Generate Cypress Tests with Fluent API

import { CypressGenerator } from 'vineguard-test-cultivator';

// Generate Page Object with fluent API
const homePage = CypressGenerator.generatePageObject({
  pageName: 'Home',
  route: '/',
  elements: [
    { name: 'heading', selector: 'h1', type: 'text' },
    { name: 'ctaButton', selector: '[data-testid="cta"]', type: 'button' }
  ]
});

// Generates class with method chaining:
// homePage.visit().assertHeadingVisible().clickCtaButton();

// Generate custom commands
const commands = CypressGenerator.generateCustomCommands();
const commandTypes = CypressGenerator.generateCustomCommandsTypes();

// Includes: login, logout, checkAuth, interceptAPI, waitForAPI,
// setLocalStorage, getLocalStorage, assertToast, and more

API Reference

JestGenerator

generateMSWHandlers(routes)

Generate MSW handlers for API routes with success and error scenarios.

const handlers = JestGenerator.generateMSWHandlers([
  { path: '/api/users', method: 'GET', middleware: ['auth'] }
]);
// Returns: MSW handler code as string

generateMSWSetup()

Generate MSW setup files (server.ts, setupTests.ts, browser.ts).

const setup = JestGenerator.generateMSWSetup();
console.log(setup.server);      // Node/Jest setup
console.log(setup.setupTests);  // Jest configuration
console.log(setup.browser);     // Browser setup

generateComponentTestWithMSW(options)

Generate component test with MSW API mocking.

const test = JestGenerator.generateComponentTestWithMSW({
  componentName: 'UserProfile',
  filePath: 'src/components/UserProfile.tsx',
  testType: 'integration',
  isComponent: true,
  isReact: true,
  useMSW: true,
  apiEndpoint: '/api/users/1',
  apiMethod: 'GET'
});

generateTest(options)

Generate Jest test (unit, integration, or accessibility).

const test = JestGenerator.generateTest({
  componentName: 'Button',
  filePath: 'src/components/Button.tsx',
  testType: 'unit',
  isComponent: true,
  isReact: true,
  hasProps: true,
  hasState: false
});

PlaywrightGenerator

generateBasePage()

Generate BasePage class with 20+ common utilities.

const basePage = PlaywrightGenerator.generateBasePage();
// Includes: navigate, waitForElement, clickElement, fillInput,
// selectOption, isVisible, takeScreenshot, assertVisible, etc.

generatePageObject(options)

Generate page-specific Page Object Model.

const pageObject = PlaywrightGenerator.generatePageObject({
  pageName: 'Dashboard',
  route: '/dashboard',
  elements: [
    { name: 'welcomeText', selector: 'h1', type: 'text' },
    { name: 'logoutButton', selector: '[data-testid="logout"]', type: 'button' }
  ]
});

generatePageObjectsFromFlows(userFlows)

Generate multiple POMs from user flows.

const pageObjects = PlaywrightGenerator.generatePageObjectsFromFlows([
  {
    name: 'Checkout Flow',
    steps: [
      { route: '/cart', action: 'visit' },
      { route: '/checkout', action: 'navigate' },
      { route: '/payment', action: 'fill', selector: '[data-testid="card"]' }
    ]
  }
]);
// Returns: { BasePage, CartPage, CheckoutPage, PaymentPage }

generateTestWithPOM(options)

Generate E2E test using Page Object Model.

const test = PlaywrightGenerator.generateTestWithPOM({
  flowName: 'User Registration',
  steps: [
    { description: 'Navigate to signup', pageName: 'Signup', action: 'goto' },
    { description: 'Fill form', pageName: 'Signup', action: 'fillForm' },
    { description: 'Submit', pageName: 'Signup', action: 'clickSubmitButton' }
  ],
  baseUrl: 'http://localhost:3000'
});

CypressGenerator

generatePageObject(options)

Generate Cypress Page Object with fluent API and singleton pattern.

const pageObject = CypressGenerator.generatePageObject({
  pageName: 'Login',
  route: '/login',
  elements: [
    { name: 'emailInput', selector: '[data-testid="email"]', type: 'input' },
    { name: 'passwordInput', selector: '[data-testid="password"]', type: 'input' },
    { name: 'loginButton', selector: '[data-testid="login-btn"]', type: 'button' }
  ]
});
// Generates fluent API: loginPage.visit().typeEmail('test@example.com').typePassword('pass').clickLoginButton();

generateCustomCommands()

Generate 13 reusable Cypress custom commands.

const commands = CypressGenerator.generateCustomCommands();
// Includes: login, logout, checkAuth, interceptAPI, waitForAPI,
// fillFormField, assertToast, setLocalStorage, getLocalStorage,
// clearAllStorage, seedDatabase, resetDatabase, screenshot

generateCustomCommandsTypes()

Generate TypeScript declarations for custom commands.

const types = CypressGenerator.generateCustomCommandsTypes();
// Full TypeScript support with JSDoc comments for all custom commands

Utility Functions

import {
  extractRouteParams,
  generateMockData,
  inferLocatorStrategy,
  sanitizeTestName,
  groupRoutesByResource,
  routeToDescription,
  getStatusCodeDescription,
  camelToHuman,
  generateTestId,
  isDetailRoute,
  isListRoute,
  inferHttpMethods
} from 'vineguard-test-cultivator';

// Extract parameters from route
const params = extractRouteParams('/api/users/:id/posts/:postId');
// Returns: ['id', 'postId']

// Generate mock data for resource
const mockUser = generateMockData('users');
// Returns: { id: 1, email: 'test@example.com', name: 'Test User', ... }

// Infer best locator strategy
const locator = inferLocatorStrategy('button');
// Returns: 'role="button"'

// Sanitize test name
const testName = sanitizeTestName('should!@# test-something');
// Returns: 'Should test something'

High-Level API

import {
  generateTestSuiteWithMSW,
  generateE2ETestsWithPOM,
  generateCompleteTestSuite
} from 'vineguard-test-cultivator';

// Generate complete MSW test suite
const mswSuite = generateTestSuiteWithMSW(apiRoutes, {
  includeErrorScenarios: true,
  includeValidation: true
});

// Generate E2E tests with POM
const e2eSuite = generateE2ETestsWithPOM(userFlows, 'playwright');

// Generate complete test suite from project scan
const completeSuite = generateCompleteTestSuite(scanResult, {
  msw: true,
  pom: true,
  framework: 'playwright'
});

Type Definitions

All type definitions are fully exported for TypeScript users:

import type {
  MSWOptions,
  POMOptions,
  EnhancedGeneratorOptions,
  Route,
  UserFlow,
  UserFlowStep,
  Element,
  PageDefinition,
  TestSuiteConfig,
  TestArtifact,
  JestTestOptions,
  CypressTestOptions,
  PlaywrightTestOptions
} from 'vineguard-test-cultivator';

Examples

See the EXAMPLES.md file for comprehensive usage examples including:

  • Complete MSW setup for Jest
  • Playwright POM with real user flows
  • Cypress fluent API patterns
  • Integration with VineGuard project scanning
  • Custom test generation workflows

Best Practices

MSW Integration

  1. Use network-level mocking for realistic API testing
  2. Test all scenarios: success (200, 201), validation (400), auth (401), not found (404), errors (500)
  3. Reset handlers between tests with server.resetHandlers()
  4. Override handlers per test using server.use() for specific scenarios

Page Object Model

  1. Separate concerns: Keep locators, actions, and assertions separate
  2. Use reliable locators: Prefer data-testid, role, label, text over CSS selectors
  3. Keep POMs thin: One page = one Page Object
  4. Reuse BasePage: Common utilities belong in BasePage (Playwright)
  5. Fluent API: Use method chaining for readable tests (Cypress)

Test Organization

  1. Group by feature: Organize tests by application feature
  2. Follow AAA pattern: Arrange, Act, Assert
  3. One assertion per test: Keep tests focused
  4. Descriptive names: Test names should explain what they test and why

Contributing

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

License

MIT © Ian Dave Divinagracia

Version History

v2.1.0 (2025-10-13)

  • ✨ Added MSW integration for Jest tests
  • ✨ Added Playwright Page Object Model generation
  • ✨ Added Cypress POM with fluent API and custom commands
  • ✨ Added 15+ utility functions
  • ✨ Added 10+ type definitions
  • ✨ Added high-level API functions

v2.0.0

  • Initial release with Jest, Playwright, and Cypress generators
  • Component testing support
  • Test organization utilities