README.md

@vitest/web-worker

Web Worker support for Vitest testing. Doesn't require JSDom.

Simulates Web Worker, but in the same thread.

Supported:

• new Worker(path)
• new SharedWorker(path)
• import MyWorker from './worker?worker'
• import MySharedWorker from './worker?sharedworker'

Installing

# with npm
npm install -D @vitest/web-worker

# with pnpm
pnpm install -D @vitest/web-worker

# with yarn
yarn install -D @vitest/web-worker

Usage

Just import @vitest/web-worker in your test file to test only in current suite.

Or add @vitest/web-worker in your setupFiles, if you want to have a global support.

import { defineConfig } from 'vitest/node'

export default defineConfig({
  test: {
    setupFiles: ['@vitest/web-worker'],
  },
})

You can also import defineWebWorkers from @vitest/web-worker/pure to defined workers, whenever you need:

import { defineWebWorkers } from '@vitest/web-worker/pure'

if (process.env.SUPPORT_WORKERS)
  defineWebWorkers({ clone: 'none' })

It accepts options:

• clone: 'native' | 'ponyfill' | 'none'. Defines how should Worker clone message, when transferring data. Applies only to Worker communication. SharedWorker uses MessageChannel from Node's worker_threads module, and is not configurable.

Note Requires Node 17, if you want to use native structuredClone. Otherwise, it fallbacks to polyfill, if not specified as none. You can also configure this option with VITEST_WEB_WORKER_CLONE environmental variable.

Examples

// worker.ts
self.onmessage = (e) => {
  self.postMessage(`${e.data} world`)
}

// worker.test.ts
import '@vitest/web-worker'
import MyWorker from '../worker?worker'

let worker = new MyWorker()
// new Worker is also supported
worker = new Worker(new URL('../src/worker.ts', import.meta.url))

worker.postMessage('hello')
worker.onmessage = (e) => {
  // e.data equals to 'hello world'
}

Notes

• Worker does not support onmessage = () => {}. Please, use self.onmessage = () => {}.
• Shared worker does not support onconnect = () => {}. Please, use self.onconnect = () => {}.
• Transferring Buffer will not change its byteLength.
• You have access to shared global space as your tests.
• You can debug your worker, using DEBUG=vitest:web-worker environmental variable.