vitest-websocket-mock 0.7.0 → 0.8.0

package/README.md

@@ -1,11 +1,15 @@
-# Vitest websocket mock
+# vitest-websocket-mock
 
 [![npm version](https://badge.fury.io/js/vitest-websocket-mock.svg)](https://badge.fury.io/js/vitest-websocket-mock)
 [![Build Status](https://github.com/akiomik/vitest-websocket-mock/actions/workflows/ci.yml/badge.svg)](https://github.com/akiomik/vitest-websocket-mock/actions)
 [![codecov](https://codecov.io/gh/akiomik/vitest-websocket-mock/branch/main/graph/badge.svg?token=40OVYIT90L)](https://codecov.io/gh/akiomik/vitest-websocket-mock)
 
-A set of utilities and Vitest matchers to help testing complex websocket interactions.
-A patched fork of [romgain/jest-websocket-mock](https://github.com/romgain/jest-websocket-mock).
+A set of utilities and Vitest matchers to help testing complex websocket interactions:
+mock websocket servers, wait for connections and messages, and assert on them
+with dedicated matchers.
+
+Originally forked from [romgain/jest-websocket-mock](https://github.com/romgain/jest-websocket-mock),
+and since developed independently as a Vitest-first library.
 
 **Examples:**
 Several examples are provided in the [examples folder](https://github.com/akiomik/vitest-websocket-mock/blob/main/examples/).
@@ -15,8 +19,31 @@ In particular:
 - [testing a component using the saga above](https://github.com/akiomik/vitest-websocket-mock/blob/main/examples/redux-saga/src/__tests__/App.test.tsx)
 - [testing a component that manages a websocket connection using react hooks](https://github.com/akiomik/vitest-websocket-mock/blob/main/examples/hooks/src/App.test.tsx)
 
+## When to use this vs. MSW
+
+[Vitest recommends](https://vitest.dev/guide/mocking/requests) [Mock Service Worker (MSW)](https://mswjs.io)
+for mocking network requests, and MSW has first-class
+[WebSocket support](https://mswjs.io/docs/websocket/). The two address different
+layers of the problem:
+
+- **MSW** provides declarative, network-level mocking (`ws.link()` handlers).
+  It shines when you want to share handlers between your app, Storybook, and
+  tests, or when you also need to mock HTTP or GraphQL.
+- **`vitest-websocket-mock`** provides imperative test-flow ergonomics that MSW
+  does not: a `WS` mock-server object, `await server.connected`, a synchronous
+  record of received messages in `server.messages`, and custom matchers such as
+  `.toReceiveMessage` and `.toHaveReceivedMessages`.
+
+If your test reads best as a step-by-step conversation with a mock server
+("wait for the connection, assert on the next message, reply, assert again"),
+this library is the better fit. Running this library on top of MSW's
+interceptor, which would make the two complementary rather than alternatives,
+is being explored in [#77](https://github.com/akiomik/vitest-websocket-mock/issues/77).
+
 ## Install
 
+`vitest-websocket-mock` requires Vitest 5 as a peer dependency.
+
 ```bash
 npm install -D vitest-websocket-mock
 ```
@@ -65,7 +92,7 @@ const server = new WS('ws://localhost:1234', { jsonProtocol: true });
 server.send({ type: 'GREETING', payload: 'hello' });
 ```
 
-- The `mock-server` options `verifyClient` and `selectProtocol` are directly passed-through to the mock-server's constructor.
+- The [`mock-socket`](https://github.com/thoov/mock-socket) server options `verifyClient` and `selectProtocol` are directly passed through to the underlying mock server's constructor.
 
 ### Attributes of a `WS` instance
 
@@ -98,8 +125,9 @@ A `WS` instance has the following attributes:
 
 ## Run assertions on received messages
 
-`vitest-websocket-mock` registers custom vitest matchers to make assertions
-on received messages easier:
+`vitest-websocket-mock` registers custom Vitest matchers to make assertions
+on received messages easier. They are registered automatically when
+`vitest-websocket-mock` is imported, so no extra setup file is needed:
 
 - `.toReceiveMessage`: async matcher that waits for the next message received
   by the mock websocket server, and asserts its content. It will time out
@@ -329,6 +357,19 @@ You can work around this by installing the setImmediate shim from
 [https://github.com/YuzuJS/setImmediate](https://github.com/YuzuJS/setImmediate) and
 adding `require('setimmediate');` to your `setupTests.js`.
 
+### The custom matchers are not recognized by TypeScript
+
+```
+Property 'toReceiveMessage' does not exist on type 'Assertion<void, WS>'.
+```
+
+The matchers are contributed with [module augmentation][augmentation], which
+only merges into the copy of `vitest` the augmentation resolves to. Deduplicate
+`vitest` if your project resolves more than one, for example a monorepo where a
+nested package pins its own.
+
+[augmentation]: https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
+
 ## Testing React applications
 
 When testing React applications, `vitest-websocket-mock` will look for
@@ -377,9 +418,3 @@ the `mock-socket` library that `vitest-websocket-mock` uses under the hood only
 implements the browser API.
 As a result, `vitest-websocket-mock` will only work with the `ws` library if you
 restrict yourself to the browser APIs!
-
-## Examples
-
-For a real life example, see the
-[examples directory](https://github.com/akiomik/vitest-websocket-mock/tree/main/examples),
-and in particular the saga tests.

package/dist/index.d.ts

@@ -1,10 +1,10 @@
+import { Matcher } from "vitest";
 import { Client, CloseOptions, Server, ServerOptions } from "mock-socket";
-import { RawMatcherFn } from "@vitest/expect";
 //#region src/derivers/deriveToHaveReceivedMessage.d.ts
-declare function deriveToHaveReceivedMessage(name: string, fn: RawMatcherFn): RawMatcherFn;
+declare function deriveToHaveReceivedMessage(name: string, fn: Matcher): Matcher;
 //#endregion
 //#region src/derivers/deriveToReceiveMessage.d.ts
-declare function deriveToReceiveMessage(name: string, fn: RawMatcherFn): RawMatcherFn;
+declare function deriveToReceiveMessage(name: string, fn: Matcher): Matcher;
 //#endregion
 //#region src/derivers/types.d.ts
 /**
@@ -32,7 +32,7 @@ interface WSOptions extends ServerOptions {
   jsonProtocol?: boolean;
 }
 type DeserializedMessage<TMessage = object> = string | TMessage;
-declare class WS {
+export default class WS {
   server: Server;
   serializer: (deserializedMessage: DeserializedMessage) => string;
   deserializer: (message: string) => DeserializedMessage;
@@ -54,14 +54,13 @@ declare class WS {
 //#endregion
 //#region src/matchers/index.d.ts
 interface CustomMatchers<R = unknown> {
-  toReceiveMessage<TMessage = object>(message: DeserializedMessage<TMessage>, options?: ReceiveMessageOptions): Promise<R>;
+  toReceiveMessage<TMessage = object>(message: DeserializedMessage<TMessage>, options?: ReceiveMessageOptions): Promise<void>;
   toHaveReceivedMessages<TMessage = object>(messages: Array<DeserializedMessage<TMessage>>): R;
 }
 //#endregion
 //#region src/extend-expect.d.ts
-declare module '@vitest/expect' {
-  interface Assertion<T = any> extends CustomMatchers<T> {}
-  interface AsymmetricMatchersContaining extends CustomMatchers {}
+declare module 'vitest' {
+  interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> extends CustomMatchers<R> {}
 }
 //#endregion
-export { type ReceiveMessageOptions, WS, WS as default, deriveToHaveReceivedMessage, deriveToReceiveMessage };
+export { type ReceiveMessageOptions, WS, deriveToHaveReceivedMessage, deriveToReceiveMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-websocket-mock",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Mock websockets and assert complex websocket interactions with Vitest",
   "type": "module",
   "repository": {
@@ -37,15 +37,15 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
     "@types/node": "^26.1.1",
-    "@vitest/coverage-v8": "^4.1.10",
-    "rimraf": "^4.1.2",
-    "tsdown": "^0.22.5",
+    "@vitest/coverage-v8": "^5.0.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
-    "vitest": ">=4"
+    "vitest": ">=5 <6"
   },
   "dependencies": {
     "mock-socket": "^9.2.1"