@capillarytech/cap-ui-dev-tools

Development tools for Capillary UI projects - Webpack hot-reload plugin + CapVision session recording

📦 What's Included

1. 🔥 Library Watcher Plugin (Webpack)

A "zero-config" webpack plugin that automatically aliases and hot-reloads local libraries.

2. 🎥 CapVision Session Recording (NEW in v1.1.0)

Automatic session recording for WebdriverIO tests with HTML report integration.

🚀 Quick Start

Installation

npm install --save-dev @capillarytech/cap-ui-dev-tools

Feature 1: Webpack Library Watcher Plugin

The Problem

When developing an application that consumes a local library, you typically have to manage two separate configurations:

1. Webpack Alias: You need to add a resolve.alias entry in your webpack config to point the library's package name to your local source code.
2. File Watcher: You need a separate mechanism to watch for changes in that local source code to trigger a rebuild.

Managing this in the main webpack config can be messy and error-prone.

The Solution

This plugin provides a single, clean interface to handle both aliasing and watching.

Based on initial testing, this can reduce development iteration time by over 90% (e.g., from 3 minutes to under 10 seconds).

Usage

// webpack.config.js
const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools');
// or
const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools/webpack');

const path = require('path');

module.exports = {
  mode: 'development',
    // ... your other webpack config

    // NO need for a separate resolve.alias block for local development!
    // The plugin handles it for you.
    resolve: {
      // ... any other aliases can stay here
    },

  plugins: [
    new webpack.HotModuleReplacementPlugin(),
    
    new LibraryWatcherPlugin({
      // An array of libraries to alias and watch.
      libs: [
        {
          // The package name of the library (from its package.json).
          name: 'cap-creatives-ui',
          
          // The absolute path to the library's source code.
          path: path.resolve(__dirname, '../cap-creatives-ui/src')
        },
        {
          name: 'another-local-lib',
          path: path.resolve(__dirname, '../another-local-lib/src')
        }
      ],
      
      // Enable verbose logging to the console.
      verbose: true,
      
      // Optional: Options passed directly to chokidar.
      watchOptions: {
        // ..
      }
    })
  ]
};

How It Works

1. During initialization, the plugin reads your libs array.
2. It programmatically modifies webpack's configuration, adding a resolve.alias entry for each library.
3. It then uses chokidar to watch the provided path for each library.
4. It adds the watched paths to webpack's contextDependencies to make webpack aware of them.
5. When a file change is detected, the plugin tells webpack's own watcher that the file has been invalidated, triggering a standard recompilation and HMR update.

Feature 2: CapVision Session Recording (NEW ✨)

Quick Start

// wdio.conf.js
const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');

const capVisionHooks = createWDIOCapVisionHooks({
  recordingsOutputDir: './reports/recordings',
  enabledClusters: ['staging', 'production']
});

exports.config = {
  onPrepare: capVisionHooks.onPrepare,
  beforeTest: (test, context) => capVisionHooks.beforeTest(test, context, browser),
  afterTest: capVisionHooks.afterTest,
  onComplete: capVisionHooks.onComplete
};

Features

• ✅ Automatic Recording - Zero manual intervention
• ✅ Page Refresh Support - Maintains recording across navigations
• ✅ HTML Report Integration - Auto-embeds playback in reports
• ✅ Smart Filtering - Configure by cluster, module, test type
• ✅ Console Recording - Captures console logs with UI interactions
• ✅ Privacy First - Auto-masks sensitive inputs
• ✅ Framework Agnostic Core - Works with WebdriverIO, Playwright, Puppeteer
• ✅ Visual Regression Mode (v1.1.0) - Record ALL tests (pass/fail) for visual verification

Full Documentation

See CAPVISION_USAGE.md for complete CapVision documentation including:

• Configuration options
• Usage patterns
• API reference
• Troubleshooting
• Examples

📦 Package Exports

// Webpack Plugin (default export)
const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools');
// or explicitly
const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools/webpack');

// CapVision Recorder
const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
// or from main export
const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools');

// Full CapVision module
const capVision = require('@capillarytech/cap-ui-dev-tools').capVisionRecorder;

🎯 Use Cases

For UI Library Developers

Use LibraryWatcherPlugin to:

• Develop and test shared components in real-time
• Eliminate slow "npm link" workflows
• See changes instantly in consuming applications

For QA/Test Engineers

Use CapVision Recorder to:

• Automatically record test sessions
• Debug test failures visually
• Share test recordings with developers
• Enhance HTML reports with playback

For Full-Stack Teams

Use both for:

• Fast UI development iteration
• Automated test documentation
• Better collaboration between dev and QA

📚 Documentation

• Webpack Plugin: See sections above
• CapVision Recorder: See CAPVISION_USAGE.md
• Integration Guide: See INTEGRATION_GUIDE.md
• Testing Guide: See TESTING_GUIDE.md

🔧 Troubleshooting

Webpack Plugin

Changes are not detected

• Check Paths: Make sure the path in the libs configuration is an absolute path pointing to the source code of your library. Use path.resolve(__dirname, '..', 'your-lib').
• Check Name: Ensure the name property matches the package name your host application is trying to import.
• Enable verbose mode: Set verbose: true to see detailed logs.

CapVision Recorder

See CAPVISION_USAGE.md for common issues and solutions.

📝 Changelog

v1.1.0 (2026-02-07)

• ✨ NEW: Visual Regression Mode — saveAllRecordings config option
• ✅ Records ALL tests (pass and fail) when saveAllRecordings: true
• ✅ On-demand visual regression suite support for module-level recording
• ✅ Automatic mode detection via VISUAL_REGRESSION environment variable
• ✅ Enhanced logging for visual regression mode status
• 📚 Updated documentation with visual regression usage guide

v2.0.0 (2025-12-20)

• ✅ Major version bump with package restructuring
• ✅ Updated dependencies

v1.1.0 (2025-11-12)

• ✨ NEW: Added CapVision session recording module
• ✅ Support for automatic test recording
• ✅ HTML report enhancement with playback
• ✅ WebdriverIO integration via hooks
• ✅ Framework-agnostic core
• 📚 Comprehensive documentation added

v1.0.0 (Initial Release)

• ✅ Webpack Library Watcher Plugin
• ✅ Hot-reload for local libraries
• ✅ Zero-config webpack integration

🚀 Publishing to NPM

For maintainers:

1. Update Version Number: Update the version field in package.json according to SemVer.

2. Log in to NPM:

   npm login

3. Perform a Dry Run:

   npm publish --dry-run

4. Publish:

   npm publish

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

ISC License

🙏 Acknowledgments

• CapVision: Session recording solution (powered by rrweb)
• Chokidar: File watching library
• Webpack: Module bundler
• WebdriverIO: Test automation framework

Made with ❤️ by Capillary Technologies

Version: 2.1.0 Includes: Webpack Hot-Reload Plugin + CapVision Session Recording + Visual Regression Mode