Plugin debugging and testing methods

Plugin Debugging and Testing Methods

In the development process of Vite.js plugins, debugging and testing are key steps to ensure functional stability. Proper debugging techniques can quickly locate issues, while comprehensive testing strategies can prevent potential defects.

Debugging Tools and Techniques

When using Chrome DevTools to debug Vite plugins, you can actively trigger breakpoints with the debugger statement:

export default function myPlugin() {
  return {
    name: 'vite-plugin-debug',
    transform(code, id) {
      debugger; // The browser will automatically pause here
      if (id.endsWith('.vue')) {
        console.log('Processing Vue file:', id);
      }
      return code;
    }
  }
}

For SSR scenarios, it is recommended to use VS Code's JavaScript Debug Terminal:

1. Press Ctrl+Shift+P to open the command palette
2. Select "JavaScript Debug Terminal"
3. Run vite dev in the terminal

Logging Strategy

Structured logging can significantly improve debugging efficiency. It is recommended to use the consola library:

import consola from 'consola';

export default {
  name: 'vite-plugin-logger',
  configResolved(config) {
    consola.box('Resolved Config:');
    consola.info({
      root: config.root,
      plugins: config.plugins.map(p => p.name)
    });
  }
}

Key logging level usage recommendations:

• consola.debug: Detailed process tracking
• consola.warn: Non-blocking issues
• consola.error: Errors requiring immediate attention

Test Environment Setup

For unit testing, Vitest + happy-dom is recommended:

// vite-plugin-svg/test/transform.spec.ts
import { describe, it, expect } from 'vitest';
import svgPlugin from '../src';

describe('SVG transform', () => {
  it('should inject viewBox attribute', async () => {
    const result = await svgPlugin().transform('<svg width="100"/>', 'test.svg');
    expect(result).toContain('viewBox="0 0 100 100"');
  });
});

Configure vite.config.test.ts to handle the test environment separately:

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    environment: 'happy-dom',
    coverage: {
      reporter: ['text', 'json', 'html']
    }
  }
});

Hook Function Testing Key Points

When testing different plugin hooks, simulate the corresponding context. For example, the config hook:

import { resolve } from 'path';

describe('Config hook', () => {
  it('should modify base path', () => {
    const plugin = myPlugin({ prefix: '/api' });
    const config = plugin.config?.call({} as any, { base: '/' });
    expect(config).toHaveProperty('base', '/api/');
  });
});

Example of simulating a complete build process:

const mockBuildContext = {
  scanGlob: '**/*.md',
  getModuleInfo: jest.fn(),
  emitFile: jest.fn()
};

test('buildEnd hook', async () => {
  await markdownPlugin().buildEnd?.call(mockBuildContext);
  expect(mockBuildContext.emitFile).toHaveBeenCalledTimes(3);
});

Real Environment Validation

Create a test project for integration testing:

mkdir test-project && cd test-project
npm init vite@latest --template vue-ts

Add a local plugin reference in package.json:

{
  "devDependencies": {
    "my-plugin": "file:../path-to-plugin"
  }
}

Use console.time to monitor performance:

export function transformMarkdown() {
  return {
    name: 'markdown-perf',
    transform(code, id) {
      if (!id.endsWith('.md')) return;

      console.time('markdown-transform');
      const result = compileMarkdown(code);
      console.timeEnd('markdown-transform');
      
      return `export default ${JSON.stringify(result)}`;
    }
  }
}

Error Boundary Handling

Force error scenarios to validate plugin robustness:

describe('Error handling', () => {
  it('should catch CSS parse errors', async () => {
    const brokenCSS = `div { color: `;
    await expect(
      cssPlugin().transform.call({ error: jest.fn() }, brokenCSS, 'broken.css')
    ).rejects.toThrow('CSS syntax error');
  });
});

Implement custom error classes to improve identifiability:

class PluginError extends Error {
  constructor(message, code) {
    super(`[vite-plugin-utils] ${message}`);
    this.code = code;
  }
}

export function handleAssets() {
  return {
    name: 'assets-handler',
    load(id) {
      if (!fs.existsSync(id)) {
        throw new PluginError(`File not found: ${id}`, 'ENOENT');
      }
    }
  }
}

Version Compatibility Testing

Matrix testing for different Vite version support:

# .github/workflows/test.yml
strategy:
  matrix:
    vite-version: ["3.0.0", "3.1.0", "4.0.0"]
steps:
  - run: npm install vite@${{ matrix.vite-version }}
  - run: npm test

Use peerDependencies to declare version requirements:

{
  "peerDependencies": {
    "vite": "^3.0.0 || ^4.0.0"
  }
}

Performance Optimization Checks

Generate performance reports with the --profile parameter:

vite build --profile

Analyze time consumption at each plugin stage:

export function analyzePlugin() {
  const timings = new Map();

  return {
    name: 'performance-analyzer',
    buildStart() {
      timings.set('start', performance.now());
    },
    buildEnd() {
      const duration = performance.now() - timings.get('start');
      console.log(`Total build time: ${duration.toFixed(2)}ms`);
    }
  }
}

Continuous Integration Practices

GitHub Actions configuration example:

name: Plugin Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm test -- --coverage
      - uses: codecov/codecov-action@v3

User Behavior Simulation

Use Playwright for end-to-end testing:

// tests/e2e.spec.ts
import { test, expect } from '@playwright/test';

test('should inject styles', async ({ page }) => {
  await page.goto('http://localhost:3000');
  const bgColor = await page.$eval('div', el => 
    getComputedStyle(el).backgroundColor
  );
  expect(bgColor).toBe('rgb(255, 0, 0)');
});

Configure a test server:

// vite.config.ts
export default defineConfig({
  plugins: [
    myPlugin(),
    {
      name: 'serve-test-server',
      configureServer(server) {
        server.middlewares.use('/api', (req, res) => {
          res.end('mock data');
        });
      }
    }
  ]
})

Cache Mechanism Validation

Test plugin caching behavior:

describe('Cache validation', () => {
  let cache;

  beforeEach(() => {
    cache = new Map();
  });

  it('should reuse cached result', async () => {
    const plugin = myPlugin({ cache });
    const firstRun = await plugin.transform('content', 'file.txt');
    const secondRun = await plugin.transform('content', 'file.txt');
    expect(firstRun).toBe(secondRun);
  });
});

Implement custom caching strategies:

export function createDiskCache(dir) {
  return {
    get(key) {
      const file = path.join(dir, key);
      return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : null;
    },
    set(key, value) {
      fs.mkdirSync(dir, { recursive: true });
      fs.writeFileSync(path.join(dir, key), value);
    }
  };
}

Multi-Process Testing

Validate plugin behavior in Worker environments:

// test/worker.spec.ts
import { Worker } from 'worker_threads';

test('works in worker thread', () => new Promise((resolve) => {
  const worker = new Worker(`
    const { parentPort } = require('worker_threads');
    const plugin = require('../dist').default();
    plugin.transform('test', 'file.js').then(() => {
      parentPort.postMessage('done');
    });
  `, { eval: true });

  worker.on('message', resolve);
}));

Configuration Validation

Use Zod for configuration validation:

import { z } from 'zod';

const configSchema = z.object({
  target: z.enum(['es2015', 'es2020']).default('es2015'),
  minify: z.boolean().optional()
});

export default function myPlugin(rawConfig) {
  const config = configSchema.parse(rawConfig);
  
  return {
    name: 'validated-plugin',
    config() {
      return {
        build: {
          target: config.target
        }
      }
    }
  }
}

Test invalid configuration scenarios:

test('should reject invalid config', () => {
  expect(() => myPlugin({ target: 'es2040' }))
    .toThrow('Invalid enum value');
});

Virtual Module Testing

Validate virtual module implementation:

describe('Virtual module', () => {
  it('should resolve virtual imports', async () => {
    const plugin = virtualPlugin({
      '@virtual': 'export default 42'
    });
    
    const result = await plugin.resolveId('@virtual');
    expect(result).toBe('\0@virtual');
    
    const loaded = await plugin.load('\0@virtual');
    expect(loaded).toContain('42');
  });
});

HMR Behavior Validation

Test hot module replacement logic:

const mockHmrContext = {
  file: '/src/main.js',
  timestamp: Date.now(),
  modules: new Set(),
  read: () => Promise.resolve('updated content')
};

test('should handle HMR update', async () => {
  const plugin = hmrPlugin();
  const result = await plugin.handleHotUpdate?.(mockHmrContext);
  expect(result).toContainEqual(
    expect.objectContaining({ file: '/src/main.js' })
  );
});

Plugin Combination Testing

Validate the collaboration of multiple plugins:

function createTestServer(plugins) {
  return createServer({
    plugins: [
      vitePlugin1(),
      vitePlugin2(),
      ...plugins
    ]
  });
}

test('plugin ordering matters', async () => {
  const server = await createTestServer([myPlugin()]);
  const result = await server.transformRequest('file.vue');
  expect(result.code).toMatchSnapshot();
});

Production Build Differences

Compare behavior between development and production environments:

export function envAwarePlugin() {
  return {
    name: 'env-aware',
    config(_, env) {
      return env.command === 'build' 
        ? { define: { __DEV__: false } }
        : { define: { __DEV__: true } };
    }
  }
}

describe('Production build', () => {
  it('should disable dev flags', () => {
    const plugin = envAwarePlugin();
    const prodConfig = plugin.config?.call({}, {}, 'build');
    expect(prodConfig.define.__DEV__).toBe(false);
  });
});

Type Safety Validation

Use tsd for type testing:

// test-d/types.test-d.ts
import { expectType } from 'tsd';
import myPlugin from '../src';

expectType<{
  name: string;
  transform?: (code: string) => string;
}>(myPlugin());

Documentation Test Synchronization

Embed test cases in documentation:

```js demo
// Verify CSS injection functionality
const result = await cssPlugin().transform(
  `.red { color: red }`, 
  'styles.css'
);
assert(result.code.includes('injected'));
```

Extract executable code from documentation with scripts:

const extractExamples = (markdown) => {
  const codeBlocks = markdown.match(/```js demo([\s\S]*?)```/g);
  return codeBlocks.map(block => 
    block.replace(/```js demo|```/g, '')
  );
};