Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(wwebjs): match a copied onboarding label across whitespace runs

Yudhi Armyndharisf30a8dce72b2
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 6875b02b1..054a062da 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -585,7 +585,8 @@ once, so the session stops instead of being silently unlinked by WhatsApp about
> minutes later and the device disappears from the phone's Linked devices list. That miss is not
> silent: when the watcher finds a visible dialog it cannot match, it logs a warning
> (`action: onboarding_dialog_unrecognized`) carrying the dialog's heading and button labels, including
-> the label to add, minutes before the unlink would happen. Because that path wipes the stored
+> the label to add, minutes before the unlink would happen. Copy that label as printed: a multi-word
+> label works, and whitespace runs compare as one space. Because that path wipes the stored
> credentials, the automatic reconnect comes back with a fresh QR on its own, so the session is
> usually already sitting at `qr_ready` rather than needing a manual start. Acknowledge the modal once
> in a browser signed in as that account, then scan the QR. It does not recur — the modal is shown
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
index 9d253f8d4..f5f5d4d64 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
@@ -18,6 +18,7 @@ import {
NAVIGATION_REINJECT_GRACE_MS,
NAVIGATION_EPISODE_CAP_MS,
} from './whatsapp-web-js.adapter';
+import { resolveOnboardingContinueLabels } from './wwebjs-onboarding';
import { getEffectiveWebVersionInfo, resolveWebVersionPin, __resetWebVersionCache } from '../wa-web-version';
import { resolveEngineInitTimeoutMs } from '../engine-init-timeout';
import * as fs from 'fs';
@@ -7625,6 +7626,23 @@ describe('probeOnboardingModal (in-page onboarding modal detection)', () => {
expect(button.click).not.toHaveBeenCalled();
});
+ // The unrecognised-dialog warning prints a label with whitespace runs collapsed, and operators are
+ // told to copy it into WWEBJS_ONBOARDING_CONTINUE_LABELS: a multi-word label must match as printed.
+ it.each([
+ ['split over elements and lines', 'Tudo\n certo'],
+ ['joined by a non-breaking space', 'Tudo\u00a0certo'],
+ ])('dismisses a confirm button whose text is %s, with the label as the warning prints it', (_how, text) => {
+ const button = el(text, { button: true });
+ nest(el('Novidades', { dialog: true }), button);
+ install([button]);
+
+ expect(probeOnboardingModal({ labels: ['Continue', 'Tudo certo'], headingOptionalFor: ['Tudo certo'] })).toEqual({
+ modalPresent: true,
+ dismissed: true,
+ });
+ expect(button.click).toHaveBeenCalledTimes(1);
+ });
+
it('matches the label exactly, so a longer string containing it is not a confirm button', () => {
const button = el('Continuar con la copia de seguridad', { button: true });
install([button]);
@@ -7642,6 +7660,21 @@ describe('probeOnboardingModal (in-page onboarding modal detection)', () => {
// another language — shows up in the logs instead of failing silently. `collectDialogDiagnostics` is
// a self-contained function for the same reason as the probe: it is stringified into the page, and
// being plain means the DOM work is unit-testable here directly.
+describe('resolveOnboardingContinueLabels', () => {
+ const original = process.env.WWEBJS_ONBOARDING_CONTINUE_LABELS;
+
+ afterEach(() => {
+ if (original === undefined) delete process.env.WWEBJS_ONBOARDING_CONTINUE_LABELS;
+ else process.env.WWEBJS_ONBOARDING_CONTINUE_LABELS = original;
+ });
+
+ it('collapses whitespace runs in a configured label, as the probe compares it', () => {
+ process.env.WWEBJS_ONBOARDING_CONTINUE_LABELS = ' Tudo certo ,Weiter,Tudo\u00a0certo, ';
+
+ expect(resolveOnboardingContinueLabels()).toEqual(['Continue', 'Tudo certo', 'Weiter', 'Tudo certo']);
+ });
+});
+
describe('collectDialogDiagnostics (in-page dialog diagnostics)', () => {
type FakeEl = {
tagName: string;
@@ -7759,6 +7792,15 @@ describe('collectDialogDiagnostics (in-page dialog diagnostics)', () => {
expect(collectDialogDiagnostics()).toEqual([{ heading: "What's new on WhatsApp Web", buttons: ['Continue'] }]);
});
+ // The other half of the copy contract the probe spec pins: this is the label operators copy.
+ it('prints a multi-word button label with its whitespace runs collapsed', () => {
+ const button = el('Tudo\n certo', { tag: 'BUTTON' });
+ const dialog = nest(el('', { role: 'dialog' }), button);
+ install([dialog, button]);
+
+ expect(collectDialogDiagnostics()).toEqual([{ heading: null, buttons: ['Tudo certo'] }]);
+ });
+
// Captured page text goes straight into the logs: a newline in it would forge extra log lines.
it('strips control characters so captured text cannot forge log lines', () => {
const heading = el("What's new\non WhatsApp Web\r\n", { role: 'heading' });
diff --git a/src/engine/adapters/wwebjs-onboarding.ts b/src/engine/adapters/wwebjs-onboarding.ts
index 66621e168..d7611982a 100644
--- a/src/engine/adapters/wwebjs-onboarding.ts
+++ b/src/engine/adapters/wwebjs-onboarding.ts
@@ -19,11 +19,17 @@ export const ONBOARDING_DEFAULT_CONTINUE_LABEL = 'Continue';
* would reject a localised modal anyway, so requiring both would make the setting useless. That is a
* deliberate, operator-opted-in loosening, bounded by requiring the button to sit inside a visible
* dialog; see {@link probeOnboardingModal}.
+ *
+ * Copy a label exactly as the unrecognised-dialog warning prints it: both sides compare with control
+ * characters and whitespace runs collapsed to one space. The warning cuts a label at 40 characters,
+ * so a longer one does not match as printed; a real confirm label is far shorter.
*/
export function resolveOnboardingContinueLabels(): string[] {
const extra = (process.env.WWEBJS_ONBOARDING_CONTINUE_LABELS ?? '')
.split(',')
- .map(label => label.trim())
+ // Whitespace runs read as one space, the same as the probe and the printed label, so a label
+ // pasted from a log with a doubled space or an NBSP still matches.
+ .map(label => label.replace(/\s+/g, ' ').trim())
.filter(Boolean);
return [ONBOARDING_DEFAULT_CONTINUE_LABEL, ...extra];
}
@@ -69,7 +75,16 @@ export function probeOnboardingModal(options?: { labels?: string[]; headingOptio
// older builds. Matching only the ASCII form means never recognising the real modal.
const heading = /what[’']?s new/i;
const candidates = Array.from(document.querySelectorAll('button, [role="button"]'))
- .map(el => ({ el, label: (el.textContent || '').trim() }))
+ // Normalised exactly like collectDialogDiagnostics prints a label, so a label copied from the
+ // warning matches a button whose text spans elements or lines. Inline: this runs in the page.
+ .map(el => ({
+ el,
+ label: (el.textContent || '')
+ // eslint-disable-next-line no-control-regex
+ .replace(/[\x00-\x1F\x7F]+/g, ' ')
+ .replace(/\s+/g, ' ')
+ .trim(),
+ }))
.filter(c => isVisible(c.el) && labels.includes(c.label));
// An operator label carries no heading check, so it has to sit inside a dialog at least: matched
// page-wide, the same word on any other button would be clicked, and every click counts toward the