docs: document unit tests and add Unit tests step to CI

- CI: rename Test step to Unit tests
- README: add Testing and linting subsection, link to Contributing
- CONTRIBUTING: expand Testing with test layout table and CI note
- ARCHITECTURE: add Testing section
- INSTALLATION: add npm test to build-from-source steps

.gitea/workflows/ci.yml

@@ -107,7 +107,7 @@ jobs:
       - name: Lint — ESLint
         run: npm run lint
 
-      - name: Test
+      - name: Unit tests
         run: npm test
 
       - name: Pack extension

README.md

@@ -183,6 +183,22 @@ npm run build:dist:all
 
 The built extension will be in `releases/Holesail-Browser-*.zip` and `.xpi`. Platform binaries will be in `releases/<platform>-<arch>/`.
 
+### Testing and linting
+
+Run the unit test suite (hostname validation, TLD data, payload schemas, message handler registry):
+
+```bash
+npm test
+```
+
+Run ESLint:
+
+```bash
+npm run lint
+```
+
+CI runs both on every push and pull request. See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full test layout and development workflow.
+
 ## Platform support
 
 | Platform | Architecture | Binary |
@@ -196,6 +212,7 @@ The built extension will be in `releases/Holesail-Browser-*.zip` and `.xpi`. Pla
 ## Documentation
 
 - [Architecture](docs/ARCHITECTURE.md) — system design, component overview, message flow
+- [Contributing](docs/CONTRIBUTING.md) — development workflow, testing, adding features
 - [Installation](docs/INSTALLATION.md) — detailed install guide for all platforms
 - [Tunneling](docs/TUNNELING.md) — virtual hosts, server tunnels, service tunnels
 - [Virtual Hosts](docs/VIRTUAL-HOSTS.md) — custom TLDs, certificate generation, deep hostnames

docs/ARCHITECTURE.md

@@ -369,3 +369,14 @@ The native host is built with the [Bare](https://github.com/holepunchto/bare) ru
 3. Native addons (`.bare` files) are embedded and extracted to a content-addressed temp directory at runtime. The build script patches addons that bare-pack cannot detect (e.g. tt-native’s `load-addon` pattern) with a host-specific resolution map so each platform binary loads the correct prebuild (e.g. Linux gets `linux-x64/tt-native.bare`, not darwin).
 
 Targets: `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-x64`.
+
+## Testing
+
+An automated unit test suite lives under `test/`. It uses Node’s built-in test runner (`node --test`) and does not require the browser or Bare runtime. Tests cover:
+
+- **Hostname validation** (`test/hostname-validator.test.js`) — virtual host hostname rules and TLD blocking
+- **TLD data** (`test/tlds.test.js`) — public TLD sets used to reject real domains
+- **Payload schemas** (`test/payload-schemas.test.js`) — native host message payload validation helpers
+- **Message handler registry** (`test/message-router.test.js`) — handler map and selected handlers with mocked dependencies
+
+Run with `npm test`. CI runs the unit tests on every push and pull request; see [CONTRIBUTING.md](CONTRIBUTING.md#testing) for the full test layout and how to add tests.

docs/CONTRIBUTING.md

@@ -220,7 +220,32 @@ To run only the host build without installing: `npm run build:host`. To run the
 
 ## Testing
 
-There is an automated test suite for hostname validation, TLD data, payload schemas, and the message handler registry. Run `npm test`. Manual testing workflow:
+### Unit tests
+
+The project includes an automated unit test suite run with Node’s built-in test runner. CI runs it on every push and pull request.
+
+**Run locally:**
+
+```bash
+npm test
+```
+
+This runs `node --test test/*.test.js`. No browser or Bare runtime is required.
+
+**Test layout:**
+
+| File | What it tests |
+|------|----------------|
+| `test/hostname-validator.test.js` | `isValidVhostHostname`, `extractBaseDomain`, `extractActiveTlds` (extension dashboard data) |
+| `test/tlds.test.js` | `REAL_TLDS` and `REAL_SLD_TLDS` contents (no private TLDs, expected public TLDs) |
+| `test/payload-schemas.test.js` | Native host payload validation (`validateSetVirtualHost`, `validateRemoveVirtualHost`, `validateStartServer`, `validateStopServer`) |
+| `test/message-router.test.js` | Message handler registry: handler map has expected command types; getSettings and getSshConnections handlers return correct shape with mocked deps |
+
+`test/setup-validator.js` sets globals required by the hostname validator when run under Node (it uses `extension/dashboard/data/tlds.js`).
+
+**Adding tests:** Add new `test/*.test.js` files and use `require('node:test')` and `require('node:assert')`. Keep tests runnable in plain Node (no Chrome, no Bare) so CI stays fast.
+
+### Manual testing workflow
 
 1. Make changes to the native host source
 2. Run `npm run build:host` to regenerate the launcher

docs/INSTALLATION.md

@@ -250,6 +250,9 @@ npm run build:dist
 
 # Build for all platforms
 npm run build:dist:all
+
+# Run unit tests (optional; CI runs these automatically)
+npm test
 ```
 
 Built artifacts: