Files
waggle-os/packages/server/tests/channels-whatsapp.test.ts
shumeiko.it 16eaf01e14 chore: scrub personal names, maintainer URLs and local paths (P2.2)
Sample data in tests, prompts and UI placeholders uses Alex Morgan
instead of the maintainer's name; decision attributions say "owner".
Personal details in two test fixtures are replaced. Local paths
(D:/Projects/...) and paths into the maintainer's planning repository
are reworded. Clone and install URLs in CONTRIBUTING.md and the getting
started guide use placeholders until the public repository location is
decided (Q9). The Benchmarks page no longer names the maintainer's
hive-mind repository, and the upstream fixes log names the main Waggle
repository instead of an internal git host.
2026-11-01 00:50:13 +01:00

484 lines
19 KiB
TypeScript

/**
* WhatsAppAdapter on whatsapp-web.js — QR surfacing, message normalization
* (DM + group, own/status/media filtering), logout vs transient disconnects,
* chunked send, and the browser lookup that feeds Puppeteer (ADR-0005).
* whatsapp-web.js and @puppeteer/browsers are mocked: no network, no browser.
*/
import { EventEmitter } from 'node:events';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const wweb = vi.hoisted(() => ({
clients: [] as Array<{ options: Record<string, unknown> }>,
}));
vi.mock('whatsapp-web.js', async () => {
const { EventEmitter: Emitter } = await import('node:events');
class LocalAuth {
constructor(readonly opts: { dataPath: string }) {}
}
class Client extends Emitter {
sends: Array<{ chatId: string; text: string }> = [];
initialized = 0;
destroyed = 0;
constructor(readonly options: Record<string, unknown>) {
super();
wweb.clients.push(this);
}
async initialize(): Promise<void> { this.initialized += 1; }
async sendMessage(chatId: string, text: string): Promise<unknown> {
this.sends.push({ chatId, text });
return {};
}
async destroy(): Promise<void> { this.destroyed += 1; }
}
return { default: { Client, LocalAuth } };
});
const puppeteerBrowsers = vi.hoisted(() => ({
detectBrowserPlatform: vi.fn<() => string | undefined>(() => 'mac_arm'),
getInstalledBrowsers: vi.fn(async (): Promise<Array<Record<string, string>>> => []),
resolveBuildId: vi.fn(async () => '150.0.0.0'),
install: vi.fn(),
uninstall: vi.fn(async () => undefined),
}));
vi.mock('@puppeteer/browsers', () => ({
...puppeteerBrowsers,
Browser: { CHROME: 'chrome' },
ChromeReleaseChannel: { STABLE: 'stable' },
}));
import {
WhatsAppAdapter,
WHATSAPP_MAX_TEXT,
type WaBrowserResolver,
type WaMessageLike,
} from '../src/local/channels/whatsapp-adapter.js';
import {
browserCandidates,
findInstalledBrowser,
resolveWhatsAppBrowser,
WhatsAppBrowserError,
} from '../src/local/channels/whatsapp-browser.js';
import type { ChannelMessage } from '../src/local/channels/types.js';
const noopLog = { info: () => undefined, warn: () => undefined };
const CHROME = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
interface FakeClient extends EventEmitter {
options: Record<string, unknown>;
sends: Array<{ chatId: string; text: string }>;
initialized: number;
destroyed: number;
}
let dir: string;
let adapter: WhatsAppAdapter | null = null;
function clientAt(index: number): FakeClient {
return wweb.clients[index] as unknown as FakeClient;
}
async function startAdapter(opts: { browserResolver?: WaBrowserResolver } = {}) {
const received: ChannelMessage[] = [];
const a = new WhatsAppAdapter({
dataDir: dir,
onMessage: async m => { received.push(m); },
log: noopLog,
browserResolver: opts.browserResolver ?? (async () => CHROME),
backoffCapMs: 10,
});
adapter = a;
await a.start();
if (!opts.browserResolver) await vi.waitFor(() => expect(wweb.clients.length).toBe(1));
return { a, received };
}
function textMessage(overrides: Partial<WaMessageLike> = {}): WaMessageLike {
return {
from: '3816x@c.us',
fromMe: false,
body: 'zdravo',
type: 'chat',
id: { _serialized: 'false_3816x@c.us_m1' },
_data: { notifyName: 'Alex' },
...overrides,
};
}
async function tick(ms = 30): Promise<void> {
await new Promise(r => setTimeout(r, ms));
}
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'waggle-wa-'));
wweb.clients.length = 0;
});
afterEach(async () => {
await adapter?.stop();
adapter = null;
fs.rmSync(dir, { recursive: true, force: true });
vi.clearAllMocks();
});
describe('WhatsAppAdapter client setup', () => {
it('launches whatsapp-web.js with the found browser and keeps its state in the data dir', async () => {
await startAdapter();
const client = clientAt(0);
const authDir = path.join(dir, 'channels', 'whatsapp');
expect(client.initialized).toBe(1);
expect((client.options.authStrategy as { opts: { dataPath: string } }).opts.dataPath).toBe(authDir);
expect(client.options.webVersionCache).toEqual({ type: 'local', path: path.join(authDir, 'web-cache') });
expect(client.options.puppeteer).toMatchObject({
executablePath: CHROME,
headless: true,
handleSIGINT: false,
handleSIGTERM: false,
});
});
it('reports the download progress while the browser is being fetched', async () => {
let finish: (value: string) => void = () => undefined;
let report: (percent: number) => void = () => undefined;
const { a } = await startAdapter({
browserResolver: onProgress => {
report = onProgress;
return new Promise<string>(resolve => { finish = resolve; });
},
});
report(42);
expect(a.getStatus().detail).toMatch(/Downloading a browser.*42%/);
expect(wweb.clients).toHaveLength(0);
finish(CHROME);
await vi.waitFor(() => expect(wweb.clients.length).toBe(1));
clientAt(0).emit('qr', 'QR-DATA');
expect(a.getStatus().detail).toBeUndefined();
});
it('stays stopped with a clear error when no browser can be found or downloaded', async () => {
const { a } = await startAdapter({
browserResolver: async () => {
throw new WhatsAppBrowserError('No Chrome, Edge or Chromium found, and downloading one failed (offline).');
},
});
await vi.waitFor(() => expect(a.getStatus().lastError).toMatch(/No Chrome, Edge or Chromium/));
await tick(50);
expect(wweb.clients).toHaveLength(0);
expect(a.getStatus().connected).toBe(false);
});
it('does not create a client when stopped while the browser is still being resolved', async () => {
let finish: (value: string) => void = () => undefined;
const { a } = await startAdapter({
browserResolver: () => new Promise<string>(resolve => { finish = resolve; }),
});
await a.stop();
finish(CHROME);
await tick(20);
expect(wweb.clients).toHaveLength(0);
adapter = null;
});
it('stops a browser left over from an earlier run before starting its own', async () => {
const warnings: string[] = [];
const release = vi.fn(async () => ({ kind: 'released' as const, pid: 4242 }));
adapter = new WhatsAppAdapter({
dataDir: dir,
onMessage: async () => undefined,
log: { info: () => undefined, warn: message => { warnings.push(message); } },
browserResolver: async () => CHROME,
releaseStaleBrowser: release,
backoffCapMs: 10,
});
await adapter.start();
await vi.waitFor(() => expect(wweb.clients.length).toBe(1));
expect(release).toHaveBeenCalledWith(path.join(dir, 'channels', 'whatsapp', 'session'));
expect(warnings.join('\n')).toMatch(/left over from an earlier run \(pid 4242\)/);
});
it('waits for the user when another running server holds the session', async () => {
const a = new WhatsAppAdapter({
dataDir: dir,
onMessage: async () => undefined,
log: noopLog,
browserResolver: async () => CHROME,
releaseStaleBrowser: async () => ({ kind: 'in-use', pid: 4242 }),
backoffCapMs: 10,
});
adapter = a;
await a.start();
await vi.waitFor(() => expect(a.getStatus().lastError).toMatch(/another Waggle server.*pid 4242/));
await tick(50);
expect(wweb.clients).toHaveLength(0);
});
});
describe('WhatsAppAdapter pairing + status', () => {
it('surfaces the QR through status and clears it once connected', async () => {
const { a } = await startAdapter();
clientAt(0).emit('qr', 'QR-DATA-1');
expect(a.getStatus().qr).toBe('QR-DATA-1');
expect(a.getStatus().connected).toBe(false);
clientAt(0).emit('authenticated');
clientAt(0).emit('ready');
expect(a.getStatus().connected).toBe(true);
expect(a.getStatus().qr).toBeUndefined();
});
it('reports paired=true once a linked session is stored on disk', async () => {
const { a } = await startAdapter();
expect(a.getStatus().paired).toBe(false);
// LocalAuth creates the profile directory before the browser starts.
fs.mkdirSync(path.join(dir, 'channels', 'whatsapp', 'session'), { recursive: true });
clientAt(0).emit('ready');
expect(a.getStatus().paired).toBe(true);
});
});
describe('WhatsAppAdapter inbound', () => {
it('normalizes a DM: sender = chat id', async () => {
const { received } = await startAdapter();
clientAt(0).emit('message', textMessage());
await tick(5);
expect(received[0]).toEqual({
platform: 'whatsapp',
chatId: '3816x@c.us',
senderId: '3816x@c.us',
senderName: 'Alex',
text: 'zdravo',
messageId: 'false_3816x@c.us_m1',
});
});
it('normalizes a group message: sender = author', async () => {
const { received } = await startAdapter();
clientAt(0).emit('message', textMessage({
from: 'grp@g.us',
author: 'u9@c.us',
body: 'group hi',
id: { _serialized: 'false_grp@g.us_m2' },
}));
await tick(5);
expect(received[0]?.senderId).toBe('u9@c.us');
expect(received[0]?.chatId).toBe('grp@g.us');
expect(received[0]?.text).toBe('group hi');
});
it('filters own messages, status updates, broadcasts, media and empty text', async () => {
const { received } = await startAdapter();
const client = clientAt(0);
client.emit('message', textMessage({ fromMe: true }));
client.emit('message', textMessage({ from: 'status@broadcast' }));
client.emit('message', textMessage({ isStatus: true }));
client.emit('message', textMessage({ broadcast: true }));
client.emit('message', textMessage({ type: 'ptt', body: '' }));
client.emit('message', textMessage({ type: 'image', body: 'a caption' }));
client.emit('message', textMessage({ body: '' }));
await tick(5);
expect(received).toEqual([]);
});
});
describe('WhatsAppAdapter disconnects', () => {
it('reconnects with a new client on transient disconnects', async () => {
await startAdapter();
clientAt(0).emit('ready');
clientAt(0).emit('disconnected', 'CONFLICT');
await vi.waitFor(() => expect(wweb.clients.length).toBeGreaterThanOrEqual(2));
expect(clientAt(0).destroyed).toBeGreaterThanOrEqual(1);
});
it('keeps the client on logout so whatsapp-web.js can show a fresh QR', async () => {
const { a } = await startAdapter();
fs.mkdirSync(path.join(dir, 'channels', 'whatsapp', 'session'), { recursive: true });
clientAt(0).emit('ready');
expect(a.getStatus().paired).toBe(true);
clientAt(0).emit('disconnected', 'LOGOUT');
expect(a.getStatus().connected).toBe(false);
expect(a.getStatus().paired).toBe(false);
expect(a.getStatus().lastError).toMatch(/new QR/i);
clientAt(0).emit('qr', 'QR-AFTER-LOGOUT');
expect(a.getStatus().qr).toBe('QR-AFTER-LOGOUT');
await tick(30);
expect(wweb.clients).toHaveLength(1);
expect(clientAt(0).destroyed).toBe(0);
});
it('does not reconnect when WhatsApp blocked the account', async () => {
const { a } = await startAdapter();
clientAt(0).emit('ready');
clientAt(0).emit('disconnected', 'TOS_BLOCK');
await tick(50);
expect(wweb.clients).toHaveLength(1);
expect(a.getStatus().lastError).toMatch(/blocked/i);
});
it('drops a rejected stored session and waits for the user', async () => {
const { a } = await startAdapter();
const sessionDir = path.join(dir, 'channels', 'whatsapp', 'session');
fs.mkdirSync(sessionDir, { recursive: true });
clientAt(0).emit('auth_failure', 'restore failed');
await vi.waitFor(() => expect(fs.existsSync(sessionDir)).toBe(false));
await tick(30);
expect(wweb.clients).toHaveLength(1);
expect(a.getStatus().lastError).toMatch(/re-pair/i);
});
it('stop() destroys the client and halts reconnection', async () => {
const { a } = await startAdapter();
const client = clientAt(0);
client.emit('ready');
await a.stop();
expect(client.destroyed).toBe(1);
client.emit('disconnected', 'CONFLICT');
await tick(50);
expect(wweb.clients).toHaveLength(1);
adapter = null;
});
});
describe('WhatsAppAdapter send', () => {
it('chunks long text and targets the chat id', async () => {
const { a } = await startAdapter();
clientAt(0).emit('ready');
await a.send('x@c.us', 'w'.repeat(WHATSAPP_MAX_TEXT + 50));
expect(clientAt(0).sends).toHaveLength(2);
expect(clientAt(0).sends[0].chatId).toBe('x@c.us');
});
it('throws when not connected', async () => {
const { a } = await startAdapter();
await expect(a.send('x@c.us', 'hi')).rejects.toThrow(/not connected/);
});
});
describe('WhatsApp browser lookup', () => {
const onlyExisting = (...paths: string[]) => (candidate: string) => paths.includes(candidate);
it('finds Chrome, then Edge, on Windows in Program Files and LOCALAPPDATA', () => {
const env = {
ProgramFiles: 'C:\\Program Files',
'ProgramFiles(x86)': 'C:\\Program Files (x86)',
LOCALAPPDATA: 'C:\\Users\\ana\\AppData\\Local',
};
const edge = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe';
const userChrome = 'C:\\Users\\ana\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe';
expect(findInstalledBrowser({ platform: 'win32', env, exists: onlyExisting(edge) })).toBe(edge);
expect(findInstalledBrowser({ platform: 'win32', env, exists: onlyExisting(edge, userChrome) }))
.toBe(userChrome);
});
it('finds Chrome, Edge or Chromium app bundles on macOS, including ~/Applications', () => {
const env = { HOME: '/Users/ana' };
const userChromium = '/Users/ana/Applications/Chromium.app/Contents/MacOS/Chromium';
const edge = '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
expect(findInstalledBrowser({ platform: 'darwin', env, exists: onlyExisting(userChromium) }))
.toBe(userChromium);
expect(findInstalledBrowser({ platform: 'darwin', env, exists: onlyExisting(userChromium, edge) }))
.toBe(edge);
expect(findInstalledBrowser({ platform: 'darwin', env, exists: onlyExisting(CHROME, edge) }))
.toBe(CHROME);
});
it('finds browsers on Linux through PATH and the standard locations', () => {
const env = { PATH: '/home/ana/bin:relative/bin:/usr/bin' };
expect(findInstalledBrowser({ platform: 'linux', env, exists: onlyExisting('/home/ana/bin/chromium') }))
.toBe('/home/ana/bin/chromium');
expect(findInstalledBrowser({ platform: 'linux', env, exists: onlyExisting('/snap/bin/chromium') }))
.toBe('/snap/bin/chromium');
expect(findInstalledBrowser({
platform: 'linux',
env,
exists: onlyExisting('/usr/bin/chromium', '/opt/google/chrome/chrome'),
})).toBe('/opt/google/chrome/chrome');
expect(browserCandidates('linux', env).some(candidate => candidate.startsWith('relative/'))).toBe(false);
});
it('prefers CHROME_PATH and PUPPETEER_EXECUTABLE_PATH over detection and skips missing ones', () => {
const custom = '/opt/custom/chrome';
const env = { CHROME_PATH: '/missing/chrome', PUPPETEER_EXECUTABLE_PATH: custom };
expect(findInstalledBrowser({ platform: 'darwin', env, exists: onlyExisting(custom, CHROME) })).toBe(custom);
expect(findInstalledBrowser({ platform: 'darwin', env: {}, exists: onlyExisting(CHROME) })).toBe(CHROME);
});
it('returns null when nothing is installed', () => {
for (const platform of ['win32', 'darwin', 'linux'] as const) {
expect(findInstalledBrowser({ platform, env: {}, exists: () => false })).toBeNull();
}
});
it('uses an installed browser without loading the downloader', async () => {
const resolved = await resolveWhatsAppBrowser({
dataDir: dir, platform: 'darwin', env: {}, exists: onlyExisting(CHROME),
});
expect(resolved).toEqual({ executablePath: CHROME, source: 'installed' });
expect(puppeteerBrowsers.install).not.toHaveBeenCalled();
});
it('reuses a browser downloaded earlier into <dataDir>/browsers', async () => {
const earlier = path.join(dir, 'browsers', 'chrome', 'mac_arm-149', 'chrome');
puppeteerBrowsers.getInstalledBrowsers.mockResolvedValueOnce([
{ browser: 'chrome', platform: 'mac_arm', buildId: '149', executablePath: earlier },
]);
const resolved = await resolveWhatsAppBrowser({
dataDir: dir, platform: 'darwin', env: {}, exists: onlyExisting(earlier),
});
expect(resolved).toEqual({ executablePath: earlier, source: 'downloaded' });
expect(puppeteerBrowsers.getInstalledBrowsers).toHaveBeenCalledWith({ cacheDir: path.join(dir, 'browsers') });
expect(puppeteerBrowsers.install).not.toHaveBeenCalled();
});
it('downloads Chrome into <dataDir>/browsers when nothing is installed, reporting progress', async () => {
const downloaded = path.join(dir, 'browsers', 'chrome', 'mac_arm-150', 'chrome');
const partial = { browser: 'chrome', platform: 'mac_arm', buildId: '148', executablePath: '/gone' };
puppeteerBrowsers.getInstalledBrowsers.mockResolvedValueOnce([partial]);
puppeteerBrowsers.install.mockImplementationOnce(async (opts: {
downloadProgressCallback: (done: number, total: number) => void;
}) => {
opts.downloadProgressCallback(50, 200);
opts.downloadProgressCallback(200, 200);
return { executablePath: downloaded };
});
const progress: number[] = [];
const resolved = await resolveWhatsAppBrowser({
dataDir: dir, platform: 'darwin', env: {}, exists: () => false, onProgress: p => progress.push(p),
});
expect(resolved).toEqual({ executablePath: downloaded, source: 'downloaded' });
expect(puppeteerBrowsers.uninstall).toHaveBeenCalledWith(expect.objectContaining({ buildId: '148' }));
expect(puppeteerBrowsers.install).toHaveBeenCalledWith(expect.objectContaining({
browser: 'chrome',
buildId: '150.0.0.0',
cacheDir: path.join(dir, 'browsers'),
platform: 'mac_arm',
}));
expect(progress).toEqual([25, 100]);
});
it('fails with a clear error when nothing is installed and the download fails', async () => {
puppeteerBrowsers.install.mockRejectedValueOnce(new Error('getaddrinfo ENOTFOUND'));
const lookup = resolveWhatsAppBrowser({ dataDir: dir, platform: 'linux', env: {}, exists: () => false });
await expect(lookup).rejects.toBeInstanceOf(WhatsAppBrowserError);
await expect(lookup).rejects.toThrow(/No Chrome, Edge or Chromium found.*ENOTFOUND.*CHROME_PATH/);
});
it('fails with a clear error when there is no Chrome download for this system', async () => {
puppeteerBrowsers.detectBrowserPlatform.mockReturnValueOnce(undefined);
await expect(resolveWhatsAppBrowser({ dataDir: dir, platform: 'linux', env: {}, exists: () => false }))
.rejects.toThrow(/no Chrome download for this system/);
expect(puppeteerBrowsers.install).not.toHaveBeenCalled();
});
});