@capillarytech/cap-ui-dev-tools

@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:

• 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.
• 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

• During initialization, the plugin reads your libs array.
• It programmatically modifies webpack's configuration, adding a resolve.alias entry for each library.
• It then uses chokidar to watch the provided path for each library.
• It adds the watched paths to webpack's contextDependencies to make webpack aware of them.
• 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:

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

• Log in to NPM:

  npm login
  

• Perform a Dry Run:

  npm publish --dry-run
  

• Publish:

  npm publish
  

🤝 Contributing

Contributions welcome! Please:

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• 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