WebdriverIO Hot Reload Service

A WebdriverIO service that provides hot reloading capabilities for page objects and other modules during test execution.

Features

• Hot Module Reloading: Automatically reload modules when their source files change
• Auto-Reloading Page Objects: Page objects automatically refresh before each method call
• Standard Import Syntax: No need to change how you import modules
• Automatic Registration: Auto-discovers and registers page objects
• File Watching: Watches specified paths for changes and purges cache

Installation

npm install wdio-hot-reload-service --save-dev

Configuration

Add the service to your wdio.conf.js or wdio.conf.ts file:

// wdio.conf.js
const HotReloadService = require('wdio-hot-reload-service').default;

exports.config = {
  // ...
  services: [
    [HotReloadService, {
      debug: false,
      watchPaths: ['./test/**/*.ts', './src/**/*.ts'],
      exclude: ['node_modules', 'dist', '.git'],
      reloadMode: 'both',
      pageObjectsDir: './test/pageobjects',
      autoRegisterPageObjects: true
    }]
  ],
  // ...
};

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | debug | boolean | false | Enable debug logging | | watchPaths | string[] | ['./test//*.ts', './src//*.ts'] | File patterns to watch for changes | | exclude | string[] | ['node_modules', 'dist', '.git'] | File patterns to exclude from watching | | reloadMode | 'onChange' | 'onCall' | 'both' | 'both' | When to reload modules | | pageObjectsDir | string | './test/pageobjects' | Directory containing page objects | | autoRegisterPageObjects | boolean | true | Auto-discover and register page objects |

Usage

Using Page Objects

Once configured, the service automatically registers all page objects found in the specified directory. You can access them in your tests:

// Import directly from the service
import { getPageObject } from 'wdio-hot-reload-service';

// Get a specific page object
const LoginPage = getPageObject('LoginPage');
LoginPage.login('username', 'password');

// Or access all page objects
const allPageObjects = getAllPageObjects();

Custom Page Object Index

For better TypeScript support, you can create an index file that uses the service:

// test/pageobjects/index.ts
import { getPageObject, getAllPageObjects } from 'wdio-hot-reload-service';

// Type-safe exports
export const LoginPage = getPageObject<typeof import('./login.page').LoginPage>('LoginPage');
export const HomePage = getPageObject<typeof import('./home.page').HomePage>('HomePage');

// Re-export helper functions
export { getPageObject, getAllPageObjects };

Then import from this index in your tests:

import { LoginPage, HomePage } from '../pageobjects';

// Page objects are auto-reloaded when their source files change
LoginPage.login('username', 'password');
HomePage.checkDashboard();

How It Works

1. File Watching: The service watches specified file paths for changes
2. Cache Purging: When a file changes, it's purged from Node.js's require cache
3. Proxy Handling: Page objects are wrapped in proxies that load fresh versions
4. Method Interception: When a method is called, the proxy loads the latest version

Best Practices

1. Page Object Organization:

   • Keep page objects in a dedicated directory
   • Follow naming conventions (*.page.ts)
   • Expose clear, well-documented APIs

2. Watch Configuration:

   • Only watch directories that need hot reloading
   • Exclude large directories to improve performance

3. Debug Mode:

   • Enable debug mode during development to see what's happening
   • Disable in CI/production for better performance

Troubleshooting

1. Module Not Found:

   • Check that the file exists in the watched paths
   • Ensure the class name matches the file name (LoginPage in login.page.ts)

2. Changes Not Detected:

   • Verify the file is in a watched directory
   • Check that the file isn't in an excluded pattern
   • Try increasing the debug level

3. Performance Issues:

   • Reduce the number of watched paths
   • Add more exclusions for large directories
   • Use the 'onChange' reload mode instead of 'both'

License

MIT