Phase 1: Test Suite Modernization Foundation

.eslintrc.js

@@ -24,5 +24,19 @@ module.exports = {
     globals: {
         'WebSocket': 'readonly',
         'globalThis': 'readonly'
-    }
+    },
+    overrides: [
+        {
+            files: ['test/**/*.js'],
+            excludedFiles: ['test/scripts/**/*.js'],
+            parserOptions: {
+                ecmaVersion: 2020,
+                sourceType: 'module'
+            },
+            env: {
+                es6: true,
+                node: true
+            }
+        }
+    ]
 };

.github/workflows/websocket-tests.yml

@@ -16,3 +16,4 @@ jobs:
 
       - run: npm run test
 
+      - run: npm run test:vitest

.gitignore

@@ -7,3 +7,4 @@ builderror.log
 npm-debug.log
 test/autobahn/reports*/*
 test/scripts/heapdump/*
+/coverage

CLAUDE.md

@@ -30,3 +30,11 @@
 - Before committing to git, make sure to check for lint errors with `pnpm lint:fix` and verify that all the tests pass, including the autobahn tests.
 - Before beginning work on a section of a project plan, update the project plan file to reflect what will be in progress.
 - After completing work on a section of a project plan, update it to reflect what was completed before committing your changes to git.
+- All the work we are doing right now is in service of preparing a version 2.0 release. All of our work should feed back into the `v2` branch.
+- Always create a new branch for each project execution phase, push the work to github, and open a pull request into `v2` so I can review it before merging.
+
+## Before Committing to Git
+
+- Update any relevant project plan markdown files.
+- Ensure that you have created an appropriately named branch for the work in progress.
+- Make sure `pnpm lint:fix` is run and not showing any errors.

TEST_SUITE_MODERNIZATION_PLAN.md

@@ -4,6 +4,22 @@
 
 This document outlines the comprehensive modernization of the WebSocket-Node test suite, migrating from `tape` to `Vitest` and implementing extensive test coverage across all components. The goal is to create a robust, maintainable, and comprehensive testing infrastructure.
 
+## ⚠️ Important: ES Module File Extensions
+
+**All new test files created as part of the Vitest modernization MUST use the `.mjs` extension to ensure proper ES module handling.**
+
+This is required because:
+- The core WebSocket library maintains CommonJS compatibility for ecosystem users
+- Test files use ES module syntax (`import`/`export`)
+- Without `"type": "module"` in package.json, `.js` files are treated as CommonJS
+- Using `.mjs` extension explicitly marks files as ES modules
+
+**File Extension Guidelines:**
+- ✅ New Vitest test files: `*.test.mjs` or `*.spec.mjs`
+- ✅ Test helper modules: `*.mjs` (e.g., `config.mjs`, `setup.mjs`)
+- ✅ Vitest configuration: `vitest.config.mjs`
+- ❌ Do NOT use `.js` extension for files with ES module syntax
+
 ## Current State Analysis
 
 ### Existing Test Infrastructure

package.json

@@ -37,13 +37,21 @@
   "devDependencies": {
     "buffer-equal": "^1.0.0",
     "eslint": "^8.0.0",
-    "tape": "^4.9.1"
+    "tape": "^4.9.1",
+    "vitest": "^1.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "@vitest/ui": "^1.0.0"
   },
   "config": {
     "verbose": false
   },
   "scripts": {
     "test": "tape test/unit/*.js",
+    "test:vitest": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:watch": "vitest --coverage",
     "test:autobahn": "cd test/autobahn && ./run-wstest.js",
     "lint": "eslint lib/**/*.js test/**/*.js",
     "lint:fix": "eslint lib/**/*.js test/**/*.js --fix"

test/shared/config.mjs

@@ -0,0 +1,34 @@
+// Test configuration constants for WebSocket-Node test suite
+
+export const TEST_CONFIG = {
+  // Server configuration
+  SERVER: {
+    HOST: 'localhost',
+    PORT: 8080,
+    SECURE_PORT: 8443,
+    TIMEOUT: 5000
+  },
+
+  // Client configuration
+  CLIENT: {
+    CONNECT_TIMEOUT: 5000,
+    RECONNECT_ATTEMPTS: 3,
+    RECONNECT_DELAY: 1000
+  },
+
+  // Frame configuration
+  FRAME: {
+    MAX_SIZE: 1024 * 1024, // 1MB
+    SMALL_PAYLOAD_SIZE: 125,
+    MEDIUM_PAYLOAD_SIZE: 65535,
+    LARGE_PAYLOAD_SIZE: 65536
+  },
+
+  // Test data
+  TEST_DATA: {
+    TEXT_MESSAGE: 'Hello WebSocket World!',
+    BINARY_MESSAGE: Buffer.from('Binary test data', 'utf8'),
+    EMPTY_MESSAGE: '',
+    LARGE_TEXT: 'A'.repeat(1000)
+  }
+};

test/shared/setup.mjs

@@ -0,0 +1,14 @@
+// Global test setup for WebSocket-Node test suite
+// This file runs before all tests
+
+// Set up global test configuration
+process.env.NODE_ENV = 'test';
+
+// Increase timeout for WebSocket operations
+process.env.WEBSOCKET_TIMEOUT = '10000';
+
+// Global setup function
+export function setup() {
+  // Global test setup logic can be added here
+  console.log('Setting up WebSocket-Node test environment...');
+}

test/shared/teardown.mjs

@@ -0,0 +1,8 @@
+// Global test teardown for WebSocket-Node test suite
+// This file runs after all tests
+
+// Global teardown function
+export function teardown() {
+  // Global test cleanup logic can be added here
+  console.log('Tearing down WebSocket-Node test environment...');
+}

test/smoke.test.mjs

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { TEST_CONFIG } from './shared/config.mjs';
+
+describe('Vitest Setup Validation', () => {
+  it('should run basic test', () => {
+    expect(true).toBe(true);
+  });
+
+  it('should access test configuration', () => {
+    expect(TEST_CONFIG).toBeDefined();
+    expect(TEST_CONFIG.SERVER.HOST).toBe('localhost');
+    expect(TEST_CONFIG.SERVER.PORT).toBe(8080);
+  });
+
+  it('should handle async operations', async () => {
+    const result = await Promise.resolve('test');
+    expect(result).toBe('test');
+  });
+
+  it('should support Buffer operations', () => {
+    const buffer = Buffer.from('test', 'utf8');
+    expect(buffer).toBeInstanceOf(Buffer);
+    expect(buffer.toString()).toBe('test');
+  });
+});

vitest.config.mjs

@@ -0,0 +1,27 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'test/',
+        'example/',
+        'docs/',
+        'lib/version.js'
+      ],
+      thresholds: {
+        global: {
+          branches: 80,
+          functions: 80,
+          lines: 80,
+          statements: 80
+        }
+      }
+    }
+  }
+});