Add Bun test suite with 144 tests covering pure utils, pilot state, network, and platform integration

- bunfig.toml + bun test scripts; CI workflow runs bun-test + node-smoke on PRs
- tests in test/ mirror src/ layout with reusable HAP mocks and factories
- 87% line coverage on src/; covers regression surfaces from #99/#159/#175
- minor: assign Service/Characteristic in wiz.ts constructor body (not field init) for [[Define]] semantics
- minor: tsconfig useDefineForClassFields=false (matches tsc ES2020 default)
- CLAUDE.md gains a Testing section

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kpsuperplane

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  bun-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun test --coverage
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage
+          path: coverage/
+
+  node-smoke:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm run build

.gitignore

@@ -2,4 +2,5 @@ node_modules
 dist
 .vscode
 .DS_Store
-test
+coverage
+test/hbConfig

CLAUDE.md

@@ -0,0 +1,72 @@
+# homebridge-wiz-lan — maintainer guide
+
+This file documents the consistent release ritual for this repo, derived from past tags and merge history. Follow it whenever a PR is merged or a release is cut.
+
+## Release ritual
+
+Releases are always cut as a **separate direct commit to `master`**, never bundled into a PR merge.
+
+### 1. Merge the PR
+- Use a true merge commit (no squash).
+- Dependabot PRs and human-contributor PRs are both merged the same way.
+
+### 2. Decide whether to release now or batch
+- **Release immediately** for user-visible features or fixes.
+- **Batch** for dependabot bumps and small follow-ups — fold them into the next human-driven release.
+
+### 3. Cut the release (single direct commit on `master`)
+
+In one commit, update all of:
+
+- **`package.json`** — bump `version` (semver: patch for fix, minor for feature, major for breaking).
+- **`CHANGELOG.md`** — add a new section at the top in the existing format:
+  ```
+  ## X.Y.Z
+  - [FEAT] / [FIX] short description
+  - Thank you [@handle](https://github.com/handle) for [#NN](https://github.com/kpsuperplane/homebridge-wiz-lan/pull/NN)
+  ```
+  - Use `[FEAT]` and `[FIX]` prefixes.
+  - Credit human contributors by handle + PR link. Omit credit for dependabot.
+- **`README.md` contributors block** — if this release includes a first-time external contributor, add them under the credits section in the same format as existing entries (`#### [@handle]` then `[#NN title](url)`).
+- **`package-lock.json`** — regenerate via `npm install` so it matches the new version.
+
+The commit message is just the version string, e.g. `3.2.6`.
+
+### 4. Tag and push
+- Tag the bump commit with **`vX.Y.Z`** (always include the `v` prefix — historical tags were inconsistent; new tags should standardize on `v`).
+- Push the commit and the tag to `origin/master`.
+- npm publish runs from `.github/workflows/npm-publish.yml` on tag push.
+
+## What NOT to do
+- Don't bump `package.json` inside a feature PR — the version bump is a separate maintainer commit on master.
+- Don't squash-merge — preserve the merge-commit history.
+- Don't tag the merge commit; tag the version-bump commit that follows it.
+- Don't credit dependabot in CHANGELOG or README.
+- Don't create a release per dependabot PR — batch them.
+
+## Quick reference: file touch list per release
+
+| File | Why |
+| --- | --- |
+| `package.json` | version bump |
+| `package-lock.json` | sync with new version |
+| `CHANGELOG.md` | new section with FEAT/FIX bullets and contributor credit |
+| `README.md` | add new external contributor to credits block (only if applicable) |
+
+## Testing
+
+- Test runner: **Bun** (`bun test`). Production runtime is still Node — Bun is used only for the test suite. Tests live in `test/`, mirroring the `src/` layout.
+- Run locally:
+  - `bun test` — run the suite.
+  - `bun test --coverage` — run with coverage (text + lcov reports).
+  - `bun test --watch` — watch mode for iterative work.
+- Required before cutting a release: **`bun test` must pass**. Run it before the version-bump commit in the ritual above.
+- Coverage target: **≥80% lines** on `src/` (excluding `src/index.ts`, `src/constants.ts`, `src/types.ts`). Don't lower this — instead, add tests when adding code.
+- CI runs `.github/workflows/test.yml` on every PR and push to master. Two jobs:
+  - `bun-test` runs the suite + coverage upload.
+  - `node-smoke` runs `npm run build` across Node 18/20/22 to ensure the published JS still compiles on every supported Node line.
+- When fixing a regression, add a test that would have caught it. The cache/state and network layers have history — see `test/accessories/WizLight/pilot.test.ts` for examples tied to issues #96/#101/#143/#145/#159.
+- Mocking conventions:
+  - `test/__mocks__/homebridge.ts` provides the Homebridge HAP surface (Service, Characteristic, PlatformAccessory, AdaptiveLightingController).
+  - `test/__helpers__/factories.ts` provides `makeFakeWiz()`, `makeDevice()`, `makeLightPilot()`, `makeSocketPilot()`, `FakeSocket`.
+  - For `pilot.ts` tests, stub `src/util/network`'s `getPilot`/`setPilot` via `mock.module` and synthesize replies. For `wiz.ts` tests, mock only `dgram` so the real network functions still operate on the FakeSocket.

bunfig.toml

@@ -0,0 +1,7 @@
+[test]
+# Default off — `bun test` is fast. Enable with `bun test --coverage` or the
+# test:coverage npm script.
+coverageReporter = ["text", "lcov"]
+coverageThreshold = 0.80
+coveragePathIgnorePatterns = ["src/index.ts", "src/constants.ts", "src/types.ts"]
+preload = ["./test/__helpers__/setup.ts"]

package.json

@@ -15,7 +15,9 @@
     "prepublishOnly": "npm run build",
     "postpublish": "npm run clean",
     "watch": "npm run build && npm link && nodemon",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
   },
   "engines": {
     "homebridge": "^1.6.0 || ^2.0.0-beta.0",

src/wiz.ts

@@ -13,8 +13,8 @@ import { Config, Device } from "./types";
 import { bindSocket, createSocket, registerDiscoveryHandler, sendDiscoveryBroadcast } from "./util/network";
 
 export default class HomebridgeWizLan {
-  public readonly Service: typeof Service = this.api.hap.Service;
-  public readonly Characteristic: typeof Characteristic = this.api.hap.Characteristic;
+  public readonly Service: typeof Service;
+  public readonly Characteristic: typeof Characteristic;
 
   // this is used to track restored cached accessories
   public readonly accessories: PlatformAccessory[] = [];
@@ -26,6 +26,11 @@ export default class HomebridgeWizLan {
     public readonly config: Config,
     public readonly api: API
   ) {
+    // Assign after `this.api` is set, not via field initializer — under
+    // [[Define]] class-field semantics the initializer would run before the
+    // parameter property is assigned and dereference `undefined.hap`.
+    this.Service = this.api.hap.Service;
+    this.Characteristic = this.api.hap.Characteristic;
     this.socket = createSocket(this);
 
     // When this event is fired it means Homebridge has restored all cached accessories from disk.

test/__helpers__/factories.ts

@@ -0,0 +1,92 @@
+import { EventEmitter } from "events";
+import { mock } from "bun:test";
+import type { Device, Config } from "../../src/types";
+import type { Pilot as LightPilot } from "../../src/accessories/WizLight/pilot";
+import type { Pilot as SocketPilot } from "../../src/accessories/WizSocket/pilot";
+import {
+  FakeCharacteristicCtors,
+  FakePlatformAccessory,
+  FakeServiceCtors,
+  makeFakeAPI,
+  makeFakeLogger,
+} from "../__mocks__/homebridge";
+
+export const makeDevice = (overrides: Partial<Device> = {}): Device => ({
+  ip: "10.0.0.42",
+  mac: "AABBCCDDEEFF",
+  model: "ESP01_SHRGB_03",
+  ...overrides,
+});
+
+export const makeLightPilot = (
+  overrides: Partial<LightPilot> = {},
+): LightPilot => ({
+  mac: "AABBCCDDEEFF",
+  rssi: -50,
+  src: "udp",
+  state: true,
+  dimming: 100,
+  ...overrides,
+});
+
+export const makeSocketPilot = (
+  overrides: Partial<SocketPilot> = {},
+): SocketPilot => ({
+  mac: "AABBCCDDEEFF",
+  rssi: -50,
+  src: "udp",
+  state: true,
+  ...overrides,
+});
+
+export class FakeSocket extends EventEmitter {
+  public sent: { msg: string; port: number; ip: string }[] = [];
+  public send = mock(
+    (
+      msg: string | Buffer,
+      port: number,
+      ip: string,
+      cb?: (err: Error | null) => void,
+    ) => {
+      this.sent.push({ msg: msg.toString(), port, ip });
+      cb?.(null);
+    },
+  );
+  public bind = mock(
+    (_port: number, _addr: string, cb?: () => void) => cb?.(),
+  );
+  public close = mock(() => {});
+  public setBroadcast = mock((_: boolean) => {});
+  public address = () => ({
+    family: "IPv4",
+    address: "127.0.0.1",
+    port: 38900,
+  });
+}
+
+export const makeFakeWiz = (config: Config = {} as Config) => {
+  const api = makeFakeAPI();
+  const log = makeFakeLogger();
+  const socket = new FakeSocket();
+  const wiz: any = {
+    log,
+    config,
+    api,
+    socket,
+    Service: FakeServiceCtors,
+    Characteristic: FakeCharacteristicCtors,
+    accessories: [],
+    initializedAccessories: {},
+  };
+  return wiz;
+};
+
+export const makeAccessoryWithService = (
+  serviceKey: "Lightbulb" | "Outlet" | "Television",
+  displayName = "Test Accessory",
+  uuid = "uuid-AABBCCDDEEFF",
+) => {
+  const acc = new FakePlatformAccessory(displayName, uuid);
+  acc.addService(FakeServiceCtors[serviceKey], displayName);
+  return acc;
+};

test/__helpers__/setup.ts

@@ -0,0 +1,7 @@
+// Preloaded by bunfig.toml. Quiets noisy console output during tests so a
+// failing assertion message isn't lost in a flood of logs from production
+// code paths that defensively log. Individual tests can still assert against
+// calls on the injected `wiz.log` mock — they don't go through console.
+const noop = () => {};
+console.debug = noop;
+console.info = noop;