Mục lục

Mục Tiêu Bài Học
Tóm Tắt Nhóm 25 — 12 Bài 217-228
dispatchEvent() Là Escape Hatch Tận Cùng
Cú Pháp dispatchEvent(type, eventInit?)
Bypass Toàn Bộ: Actionability + Input Pipeline
Event.isTrusted = false — Hệ Quả Bảo Mật
Khác Biệt Với force: true
Bảng So Sánh 4 Escape Hatch Nhóm 25
Use Cases Hợp Lệ
Pattern Custom Event
Khi Nào Dùng — Last Resort
Cảnh Báo: dispatchEvent Ẩn Bug UX Nghiêm Trọng
Decision Tree
6 Pitfalls Đóng Nhóm 25
Tổng Kết Nhóm 25 + Quiz 7 Câu Mix + Bài 229

1

Mục Tiêu Bài Học

Hiểu Locator.dispatchEvent(type, eventInit?) như escape hatch tận cùng: dispatch DOM event qua JavaScript API trong page context, không qua input pipeline browser.
Nắm cú pháp đầy đủ — tên event chuẩn ('click', 'input', 'change', 'focus', ...) hoặc custom event ('myAppEvent'), tham số eventInit để truyền detail, bubbles, cancelable.
Hiểu phạm vi bypass: không actionability check, không hit testing, không focus, không mouse sequence — chỉ duy nhất event được chỉ định được dispatch lên target.
Nhận biết hệ quả Event.isTrusted = false (đã cảnh báo ở bài 207): handler check isTrusted sẽ reject; security/anti-bot pattern bị block.
Phân biệt rõ với force: true: force giữ input pipeline browser (mouse event qua CDP, focus, isTrusted = true); dispatchEvent bỏ luôn pipeline (JS-created event, isTrusted = false).
Đọc bảng so sánh 4 escape hatch của Nhóm 25 — force / trial / noWaitAfter / dispatchEvent — biết cái nào tắt phase nào trong actionability lifecycle.
Biết ba use case hợp lệ: custom event app expose mà không có user gesture tương ứng, test handler logic isolated, trigger event không thể tạo bằng input vật lý.
Áp dụng pattern code cho custom event với eventInit.detail mang payload typed.
Tuân quy tắc last resort: chỉ dùng dispatchEvent khi click default, force, dispatchEvent wrappers khác đều không cover được.
Nhận biết cảnh báo: dispatchEvent ẨN bug UX nghiêm trọng — vì user thật không tự tạo được event này, mọi vấn đề về tương tác (overlay, disabled, hit testing) đều bị che hoàn toàn.
Áp dụng decision tree khi gặp bug: bug UI thì fix UI, test pass UX thì click, test handler logic thì dispatchEvent.
Tránh 6 pitfall đóng nhóm và nắm tổng kết toàn Nhóm 25 (12 bài 217-228).

2

Tóm Tắt Nhóm 25 — 12 Bài 217-228

Bài 228 đóng Nhóm 25. Trước khi vào nội dung, dựng lại bản đồ 12 bài để định vị dispatchEvent trong toàn cảnh:

Phần	Bài	Chủ đề
Triết lý + Lifecycle	217	Triết lý auto-waiting — vì sao Playwright tự đợi
Triết lý + Lifecycle	218	Actionability lifecycle — ba phase (pre / action / post)
6 Check Actionability	219	Attached — element có trong DOM tree
	220	Visible — display, visibility, opacity, bounding box
	221	Stable — bounding box không đổi qua 2 frames
	222	Enabled — không `disabled` / `aria-disabled`
	223	Editable — không `readonly` (cho input)
	224	Receives events — `elementFromPoint` trả đúng target
Ma trận tổng hợp	224	Actionability matrix — bảng đối chiếu action × check
4 Escape Hatch	225	`force: true` — bỏ pre-check actionability
	226	`trial: true` — chỉ check, không dispatch event
	227	`noWaitAfter: true` — bỏ post-action wait
	228 (bài này)	`dispatchEvent()` — bỏ cả pre-check VÀ input pipeline

Phổ escape hatch xếp theo mức độ bypass tăng dần: trial nhẹ nhất (chỉ chạy check), noWaitAfter bỏ phase post, force bỏ phase pre-check, dispatchEvent bỏ luôn phase action. Bài 228 đứng ở cực mạnh của phổ — bypass tất cả.

Vị trí của dispatchEvent trong câu chuyện Nhóm 25: sau khi học 6 check pre-action và 3 escape hatch giữ pipeline, dispatchEvent trả lời câu hỏi "khi tất cả pipeline cũng không phù hợp thì sao". Đáp án: gửi thẳng DOM event, không qua input pipeline browser. Đây cũng là điểm kết thúc tự nhiên của nhóm — không còn mức bypass nào mạnh hơn (trừ chạy JS code trực tiếp trên DOM, vốn không còn là "action" theo nghĩa Playwright).

3

`dispatchEvent()` Là Escape Hatch Tận Cùng

Locator.dispatchEvent(type, eventInit?) là method độc lập trên Locator — không phải option của click như force hay trial. Khi gọi, Playwright thực hiện:

Resolve locator về element (vẫn check attached, strict mode).
Chạy page.evaluate trong page context để tạo event tổng hợp đúng kiểu (vd new MouseEvent('click', {...}) cho event chuẩn, new CustomEvent('myEvent', {...}) cho custom).
Gọi target.dispatchEvent(event) trên DOM node.
Resolve promise ngay khi dispatchEvent trả về (synchronous DOM API).

Cơ chế thực thi này khác hoàn toàn với click/force — không có lệnh gửi qua DevTools Protocol Input.dispatchMouseEvent đến browser. Toàn bộ flow chạy JS-side, browser engine không tham gia trừ chính lúc dispatch event đến listener.

// dispatchEvent — không phải option, là method riêng
await page.locator('#btn').dispatchEvent('click');

// So với click default — qua input pipeline browser
await page.locator('#btn').click();
// → CDP Input.dispatchMouseEvent qua browser engine
// → browser tự sinh chuỗi mousemove → mousedown → mouseup → click
// → tất cả event có isTrusted = true

// So với click force — vẫn qua input pipeline, chỉ bỏ pre-check
await page.locator('#btn').click({ force: true });
// → CDP Input.dispatchMouseEvent vẫn chạy
// → input pipeline browser giữ nguyên
// → isTrusted = true

Vì sao Playwright cung cấp method này dù đã có force? Có những event không tồn tại trong input pipeline browser:

Custom event do app tự định nghĩa ('cart-item-added', 'modal-closed', 'analytics-track') — user không có cách trigger trực tiếp.
Event chỉ trigger qua programmatic API (vd 'storage' event chỉ trigger khi tab khác thay đổi localStorage, không có "user gesture" tương ứng).
Event composite không map 1-1 với gesture (vd 'reset' trên form mà không có button reset DOM-level).

Cho các case này, dispatch trực tiếp DOM API là con đường duy nhất. dispatchEvent chính thức hoá pattern này thành API Playwright (thay vì để dev phải tự viết page.evaluate tay).

4

Cú Pháp `dispatchEvent(type, eventInit?)`

Signature:

// Tham số:
//   type:      string — tên event (DOM chuẩn hoặc custom)
//   eventInit: object — init dict, tuỳ theo loại event
//   options:   { timeout? }

await locator.dispatchEvent(type: string, eventInit?: object, options?: { timeout?: number }): Promise<void>

Playwright tự chọn constructor đúng dựa trên type:

Event type	Constructor tự chọn	Init dict điển hình
`'click'`, `'dblclick'`, `'mousedown'`, `'mouseup'`, `'mousemove'`	`MouseEvent`	`{ button, clientX, clientY, bubbles, cancelable }`
`'pointerdown'`, `'pointerup'`, `'pointermove'`	`PointerEvent`	`{ pointerType, pressure, clientX, clientY }`
`'touchstart'`, `'touchend'`, `'touchmove'`	`TouchEvent`	`{ touches, changedTouches, targetTouches }`
`'keydown'`, `'keyup'`, `'keypress'`	`KeyboardEvent`	`{ key, code, ctrlKey, shiftKey }`
`'input'`, `'change'`	`Event` hoặc `InputEvent`	`{ data, inputType, bubbles }`
`'focus'`, `'blur'`	`FocusEvent`	`{ relatedTarget, bubbles: false }`
`'drag'`, `'drop'`, `'dragstart'`	`DragEvent`	`{ dataTransfer, clientX, clientY }`
Tên custom bất kỳ	`CustomEvent`	`{ detail: ... }`

// Ví dụ cú pháp đa dạng

// Event chuẩn không cần init
await page.locator('#btn').dispatchEvent('click');

// Mouse event với toạ độ tuỳ chỉnh
await page.locator('#canvas').dispatchEvent('click', {
  button: 0,
  clientX: 150,
  clientY: 200,
  bubbles: true,
  cancelable: true,
});

// Input event với data
await page.locator('input').dispatchEvent('input', {
  data: 'hello',
  inputType: 'insertText',
  bubbles: true,
});

// Keyboard event
await page.locator('input').dispatchEvent('keydown', {
  key: 'Enter',
  code: 'Enter',
  keyCode: 13,
  bubbles: true,
});

// Custom event với detail payload
await page.locator('#cart').dispatchEvent('cart-item-added', {
  detail: {
    productId: 'sku-1234',
    quantity: 2,
    price: 19.99,
  },
  bubbles: true,
});

Lưu ý quan trọng: eventInit phải đầy đủ field mà handler app sử dụng. Thiếu bubbles: true sẽ làm event không bubble lên ancestor — handler đăng ký trên parent không nhận. Thiếu cancelable: true sẽ làm preventDefault() không có tác dụng. Đây là pitfall thường gặp với dev quen click default (tất cả flag được browser tự set).

5

Bypass Toàn Bộ: Actionability + Input Pipeline

Bảng đối chiếu chính xác — dispatchEvent bypass cái gì, giữ cái gì:

Cơ chế	Tầng	`dispatchEvent` bypass?	Ghi chú
Attached (element trong DOM)	Pre-check	KHÔNG bypass	Vẫn cần node để gọi `target.dispatchEvent`.
Locator wait	Pre-check	KHÔNG bypass	Vẫn đợi locator resolve về element.
Strict mode	Pre-check	KHÔNG bypass	Match > 1 vẫn throw strict mode violation.
Visible	Actionability	BYPASS	Dispatch lên element ẩn được.
Stable	Actionability	BYPASS	Không quan tâm bounding box.
Enabled	Actionability	BYPASS	Dispatch lên button `disabled` được. Handler vẫn chạy.
Editable	Actionability	BYPASS	Dispatch `'input'` lên `readonly` được.
Receives events	Actionability	BYPASS	Không qua hit testing — event đi thẳng đến target.
Scroll into view	Pre-event	BYPASS	Không scroll. Element off-screen vẫn dispatch được.
Mouse event sequence	Input pipeline	BYPASS	Chỉ event được chỉ định, không sinh chuỗi.
Focus qua mousedown	Input pipeline	BYPASS	Element không được focus.
Hit testing browser	Input pipeline	BYPASS	Overlay không chặn — event đến đúng target.
`Event.isTrusted`	DOM	`false`	Event JS-created. Bài 207 cảnh báo.
Auto-wait sau action	Post-action	BYPASS	Resolve ngay khi dispatch trả về.

Đọc bảng: chỉ ba cơ chế trong pre-check (attached + locator wait + strict mode) còn chạy. Toàn bộ phần còn lại — actionability, scroll, input pipeline, post-wait — bị bỏ qua. Đây là escape hatch mạnh nhất trong Playwright API.

// Minh hoạ bypass triệt để

// HTML: <button id='btn' disabled style='display:none; opacity:0'>Click</button>
// Element: attached, KHÔNG visible, disabled, off-screen

// click default — fail vì không visible
await page.locator('#btn').click();
// ❌ Timeout: element is not visible

// click force — fail vì disabled (native disabled chặn click)
await page.locator('#btn').click({ force: true });
// → Mouse event dispatch, nhưng button disabled không trigger onClick

// dispatchEvent — PASS, handler onClick vẫn chạy
await page.locator('#btn').dispatchEvent('click');
// → JS-created event đi thẳng vào onClick handler
// → Native disabled không cản (vì không qua input pipeline)
// → Handler logic chạy đầy đủ

Hệ quả: dispatchEvent "luôn pass" trong rất nhiều trường hợp — chính là nguồn gốc của cảnh báo "ẩn bug" sẽ phân tích ở đoạn 12.

6

`Event.isTrusted = false` — Hệ Quả Bảo Mật

Bài 207 đã phân tích sâu cờ Event.isTrusted trong ngữ cảnh touch event. Áp dụng cho dispatchEvent: bất kể event là 'click', 'input', 'submit' hay custom name, event tạo bởi new EventConstructor(...) trong JS luôn có isTrusted = false — đây là rule chuẩn DOM, browser cố ý để phân biệt event do user agent sinh ra với event do script.

// Handler check isTrusted — pattern phổ biến trong app security

// Pattern 1: Anti-bot — chỉ chấp nhận event người dùng thật
function handleSubmit(e: Event) {
  if (!e.isTrusted) {
    console.warn('Programmatic submit blocked');
    return;
  }
  submitForm();
}

// Pattern 2: Payment confirm — yêu cầu user gesture
async function handlePayClick(e: MouseEvent) {
  if (!e.isTrusted) {
    throw new Error('Payment requires user interaction');
  }
  await stripe.confirmPayment(...);
}

// Pattern 3: OAuth popup — browser yêu cầu user gesture mới cho phép window.open
function handleOAuthBtn(e: MouseEvent) {
  if (!e.isTrusted) {
    return; // Browser sẽ block popup nếu không có user gesture
  }
  window.open('/oauth/authorize', '_blank');
}

// Tất cả pattern trên → dispatchEvent bị reject
await page.locator('#submit').dispatchEvent('click');
// ❌ Handler return sớm vì isTrusted = false
// ❌ Submit không chạy, payment không confirm, popup không mở

Áp dụng quy tắc Bài 207: nếu test cần handler chạy và app có check isTrusted, không thể dùng dispatchEvent. Alternative duy nhất là quay về API qua CDP — click default hoặc click({ force: true }) — vì hai cái này gửi mouse event qua input pipeline browser, isTrusted = true.

Đặc biệt: một số API DOM yêu cầu "transient user activation" (window.open, navigator.share, fullscreen, clipboard) — browser tự kiểm tra event nguồn có isTrusted = true không. dispatchEvent không kích hoạt được các API này, bất kể handler có check isTrusted hay không. Đây là cấp độ bảo mật cứng của browser, không bypass được từ phía Playwright.

7

Khác Biệt Với `force: true`

Bài 225 đã so sánh force với dispatchEvent ở mức input pipeline. Bài này nhấn mạnh thêm khác biệt thực tế từ góc test:

Khía cạnh	`click({ force: true })`	`dispatchEvent('click')`
Cơ chế dispatch	CDP `Input.dispatchMouseEvent` qua browser	JS `target.dispatchEvent(new MouseEvent)`
Actionability check	Bỏ	Bỏ
Input pipeline browser	Giữ	Bỏ
Mouse event sequence (mousemove → mousedown → mouseup → click)	Đầy đủ chuỗi	Chỉ event được chỉ định
Hit testing browser	Có — overlay có thể chặn	Không — đi thẳng target
Focus qua mousedown	Có (nếu focusable)	Không
`Event.isTrusted`	`true`	`false`
Trigger transient user activation	Có (window.open, share, ...)	Không
Custom event (vd `'myEvent'`)	Không hỗ trợ	Hỗ trợ
Override `clientX`/`clientY`	Không trực tiếp	Có qua `eventInit`

Quy tắc chọn dùng:

Cần user gesture thật (popup, payment, anti-bot) → click default hoặc force. Không bao giờ dispatchEvent.
Cần bypass actionability nhưng giữ chuỗi tương tác browser → force. Đây là default cho escape hatch.
Cần trigger custom event không có user gesture tương ứng → dispatchEvent. Đây là use case riêng.
Cần test handler logic isolated, không quan tâm path tương tác → dispatchEvent. Đặt câu hỏi: đây có thực sự là e2e test, hay là unit test trá hình?

// Khác biệt thực tế

// HTML: <button onClick={share} ...>Share</button>
// async function share() {
//   if (!event.isTrusted) return;
//   await navigator.share({ url: location.href });
//   // navigator.share yêu cầu transient user activation
// }

await page.locator('#share').click(); // → share thành công
await page.locator('#share').click({ force: true }); // → share thành công
await page.locator('#share').dispatchEvent('click');
// → isTrusted = false → handler return sớm
// → Kể cả nếu không check, navigator.share vẫn throw NotAllowedError

8

Bảng So Sánh 4 Escape Hatch Nhóm 25

Bảng tổng — 4 escape hatch của Nhóm 25 đặt cạnh nhau theo phase actionability lifecycle:

Phase / Cơ chế	`force: true`	`trial: true`	`noWaitAfter: true`	`dispatchEvent()`
Locator wait + strict mode	Chạy	Chạy	Chạy	Chạy
Actionability check (visible/stable/enabled/editable/receives events)	BỎ	Chạy	Chạy	BỎ
Scroll into view	Chạy	Chạy	Chạy	BỎ
Dispatch event (action thực)	Có (qua CDP)	BỎ	Có (qua CDP)	Có (qua DOM API)
Mouse event sequence	Đầy đủ	Không (không action)	Đầy đủ	Chỉ event chỉ định
Hit testing	Có	Không liên quan	Có	Không
`Event.isTrusted`	`true`	(không event)	`true`	`false`
Post-action wait (navigation, network)	Chạy	Không liên quan	BỎ	BỎ (resolve ngay)
Mức bypass	Trung bình	Thấp (verify only)	Cuối pipeline	Cao nhất
Mục đích chính	Bypass check khi UI có limit model	Smoke test "actionable không?"	Popup / download / intermediate state	Custom event, handler isolated
Cú pháp	`action({ force: true })`	`action({ trial: true })`	`action({ noWaitAfter: true })`	`locator.dispatchEvent(type, init?)`

Đọc bảng theo chiều ngang: mỗi escape hatch tác động vào một phần riêng của lifecycle. trial tác động phase action. force tác động phase pre-check. noWaitAfter tác động phase post-wait. dispatchEvent tác động cả phase pre-check, scroll, post-wait — và thay đổi cơ chế dispatch.

Đọc theo chiều dọc: ba escape hatch đầu (force, trial, noWaitAfter) là option trên action method — ngữ cảnh chỉnh hành vi action. dispatchEvent là method riêng — thay thế hoàn toàn cách tương tác.

Quy tắc thực hành: chọn escape hatch nhẹ nhất khả thi. Bắt đầu từ trial (verify), rồi force (bypass check), rồi noWaitAfter (skip post-wait), cuối cùng mới dispatchEvent (replace dispatch). Mỗi bước lên là một mức nhân nhượng giả định "test phản ánh user thật".

9

Use Cases Hợp Lệ

Ba use case mà dispatchEvent là lựa chọn hợp lệ — không có alternative tốt hơn:

Use case 1 — Custom event app expose mà không có user gesture tương ứng

App expose custom event để integration test có thể trigger flow nội bộ — vd 'cart-item-added' emit từ inventory service khi item về stock, không có button user click trigger trực tiếp. Test integration với cart UI cần fire event này để verify UI update.

// App emit custom event qua document khi inventory thay đổi
// document.addEventListener('inventory-update', (e: CustomEvent) => {
//   updateCartUI(e.detail.items);
// });

// Test: fire event để verify UI update logic
await page.locator('html').dispatchEvent('inventory-update', {
  detail: {
    items: [{ id: 'sku-1', stock: 5 }, { id: 'sku-2', stock: 0 }],
  },
  bubbles: true,
});

await expect(page.locator('[data-testid=stock-warning]')).toBeVisible();

Đặc trưng case này: event không có UI source — không phải user nào click ra. Mọi escape hatch khác không áp dụng.

Use case 2 — Test handler logic isolated

Khi test cần verify handler logic riêng (đúng tham số, xử lý đúng state), không quan tâm "user có click được không" — vd test analytics tracking trong handler onClick mà UI hiển thị có thể bị overlay che ngẫu nhiên trong CI. dispatchEvent bypass mọi tầng UI, chỉ trigger handler.

// Test verify analytics call đúng — không quan tâm UI hit testing

// Stub analytics service
await page.exposeFunction('trackAnalytics', (eventName: string, data: any) => {
  analyticsLog.push({ eventName, data });
});

// Fire click trực tiếp lên element, bỏ qua overlay/visibility
await page.locator('[data-testid=cta-button]').dispatchEvent('click');

// Verify handler tracked đúng event
expect(analyticsLog).toContainEqual({
  eventName: 'cta_clicked',
  data: { source: 'homepage_hero' },
});

Đặc trưng case này: test chuyển sang integration ở mức handler, không phải e2e ở mức user. Phải tách rõ trong test plan — không lẫn với e2e flow.

Use case 3 — Trigger event không thể tạo bằng input vật lý

Một số event không có cách trigger bằng user gesture đơn lẻ — 'beforeunload' chỉ trigger khi đóng tab/navigate, 'visibilitychange' chỉ trigger khi switch tab, 'online'/'offline' chỉ trigger khi network state đổi. Test cần verify handler các event này phải dispatch trực tiếp.

// Test handler beforeunload — save draft khi user đóng tab
// window.addEventListener('beforeunload', (e) => {
//   if (hasUnsavedChanges) {
//     saveDraft();
//     e.preventDefault();
//   }
// });

// Test setup: tạo unsaved state
await page.locator('#editor').fill('draft content');

// Fire beforeunload — không thể test bằng cách "đóng tab" trong Playwright
await page.evaluate(() => {
  window.dispatchEvent(new Event('beforeunload', { cancelable: true }));
});
// (Ở đây dùng evaluate trực tiếp vì target là window, không phải Locator;
// cùng tinh thần với dispatchEvent)

await expect(page.locator('[data-testid=draft-saved]')).toBeVisible();

Đặc trưng case này: event là system event, user không trigger được trực tiếp qua UI. dispatchEvent là cách duy nhất.

Đặc điểm chung 3 use case: không tồn tại path tương tác user nào dẫn đến event này. Đây là điều kiện cứng để dùng dispatchEvent hợp lệ. Nếu có user path (dù khó), nên dùng escape hatch giữ pipeline (force) thay vì dispatchEvent.

10

Pattern Custom Event

Use case 1 (custom event) là lý do chính dispatchEvent tồn tại như method tách riêng. Pattern code chuẩn cho custom event:

// 1. Type cho detail payload — TypeScript discipline

interface CartItemAddedDetail {
  productId: string;
  quantity: number;
  price: number;
  source: 'product-page' | 'recommendation' | 'cross-sell';
}

// 2. Helper function wrap dispatchEvent — reuse trong nhiều test

async function fireCartEvent(
  page: Page,
  detail: CartItemAddedDetail
): Promise<void> {
  await page.locator('html').dispatchEvent('cart-item-added', {
    detail,
    bubbles: true,
    cancelable: true,
  });
}

// 3. Test sử dụng helper — đọc rõ intent

test('cart updates when item added', async ({ page }) => {
  await page.goto('/cart');

  await fireCartEvent(page, {
    productId: 'sku-1234',
    quantity: 2,
    price: 19.99,
    source: 'product-page',
  });

  await expect(page.locator('[data-testid=cart-count]')).toHaveText('2');
  await expect(page.locator('[data-testid=cart-total]')).toHaveText('$39.98');
});

Lưu ý quan trọng khi viết helper:

Bubbles true: phần lớn custom event listener đăng ký trên ancestor (document, window, root component). Thiếu bubble, listener không nhận.
Cancelable true: cho phép handler call preventDefault() nếu cần. Mặc định false sẽ làm preventDefault thành no-op.
Detail có type rõ: tránh truyền object loose. Custom event không có schema browser-side, type discipline ở phía test là biện pháp duy nhất.
Target đúng tầng: chọn target hợp lý cho event bubble đến đúng listener. html hoặc body thường dùng cho global event; specific element cho component-scoped event.

Với custom event app expose hợp đồng public, helper nên đặt cùng module với type definition của event, để code consumer (test + app) cùng tham chiếu một nguồn.

11

Khi Nào Dùng — Last Resort

Quy tắc lựa chọn — dispatchEvent đứng cuối hàng các option:

Mặc định: locator.click() / fill() / check() — Playwright tự đợi actionability. Pass user-realistic.
Nếu fail vì actionability: điều tra root cause (đọc bài 225 - phần điều tra). Nếu là UI bug → fix UI. Nếu là limit model → force: true + comment.
Nếu force vẫn không cover (overlay phủ hoàn toàn, hit testing không thể bypass): điều tra tiếp — có cách dismiss overlay không? Có cách thay đổi test env không?
Nếu vẫn không có cách: chuyển sang dispatchEvent với comment đầy đủ giải thích vì sao không thể dùng cách trên.

Số liệu thực tế từ codebase health: tỉ lệ dispatchEvent hợp lệ trong test e2e thường < 1% số action calls. Nếu codebase có nhiều hơn, dấu hiệu test đã chuyển sang testing handler thay vì user flow — nên review lại scope test.

// Quy tắc red flag — không dùng dispatchEvent ở các case sau

// ❌ "Click không hoạt động vì element bị overlay" → không dispatchEvent
// → Dismiss overlay (đóng modal, scroll), hoặc force nếu UI có limit thật

// ❌ "Test flaky vì button đôi khi disabled" → không dispatchEvent
// → Fix race condition đợi button enabled, dispatchEvent chỉ giấu vấn đề

// ❌ "Click cần focus nhưng element không focusable" → không dispatchEvent
// → Add tabindex, hoặc accept không focus (giống user thật)

// ❌ "Test scroll dài, dispatch trực tiếp nhanh hơn" → không dispatchEvent
// → Test phản ánh user flow, performance test không phải lý do bypass

// ✅ "Trigger custom event 'inventory-update' app expose" → dispatchEvent OK
// ✅ "Trigger 'beforeunload' để test save draft handler" → dispatchEvent OK
// ✅ "Custom widget canvas dispatch event qua API public" → dispatchEvent OK

Pattern code review cho dispatchEvent — câu hỏi reviewer phải hỏi:

Có user path nào dẫn đến event này không? Nếu có → dispatchEvent là sai lựa chọn.
App có check isTrusted ở handler không? Nếu có → dispatchEvent sẽ bị reject ngầm.
Handler có giả định focus/hit testing chạy không? Nếu có → dispatchEvent skip → test khác production.
Có comment đầy đủ giải thích vì sao chọn dispatchEvent không? Không có → block PR.

12

Cảnh Báo: `dispatchEvent` Ẩn Bug UX Nghiêm Trọng

Mức độ ẩn bug của dispatchEvent nghiêm trọng hơn force. Lý do: force chỉ bỏ check Playwright nhưng vẫn dispatch qua input pipeline browser — nên một số bug vẫn lộ (vd hit testing trúng overlay sẽ trigger overlay handler thay vì target). dispatchEvent bỏ luôn input pipeline — toàn bộ class bug liên quan đến tương tác browser bị che hoàn toàn.

Class bug UX	click default phát hiện?	force phát hiện?	dispatchEvent phát hiện?
Element ẩn (display:none, off-screen)	Có (timeout visible)	Một phần (click 0,0)	Không
Overlay che target (modal, ad)	Có (timeout receives events)	Một phần (trigger overlay)	Không
Button disabled không có lý do	Có (timeout enabled)	Native: no-op	Không (handler chạy)
Focus không chuyển đến element	Có (qua mousedown)	Có (qua mousedown)	Không (không focus)
Animation infinite làm element flicker	Có (timeout stable)	Không	Không
Mobile viewport — button off-screen sticky	Có (timeout / scroll fail)	Một phần	Không
Pointer-events: none trên target	Có (timeout)	Một phần (hit test khác)	Không (đi thẳng target)

Insight: dispatchEvent không phát hiện được bất kỳ bug UX cấu trúc nào. Test pass nghĩa là handler logic đúng — không nói gì về user có thể trigger được handler không. Đây là điểm phân biệt rõ với e2e test thực.

Hệ quả phổ biến trong production:

Conversion blocker: button "Buy now" bị overlay che. Test dispatchEvent pass. Production user mất sale.
Form submit không hoạt động: button disabled vì validation, không có visual feedback. Test pass. User lúng túng "vì sao không submit được".
Mobile broken: button off-screen viewport. Test pass trên CI desktop. Mobile user không tap được.
Accessibility regression: focus không chuyển, screen reader không thông báo state mới. Test pass. User dùng AT bị block.

Nguyên tắc đối phó: nếu test e2e thực sự cần test user flow, không bao giờ dispatchEvent. Nếu cần handler test, viết test integration / unit riêng — không lẫn vào e2e suite.

13

Decision Tree

Decision tree khi gặp tình huống cần action — dùng cho code review hoặc tự kiểm khi viết test:

Cần tương tác với element?
├── Có user path trigger event này không?
│   ├── KHÔNG (custom event, beforeunload, visibilitychange)
│   │   └── ✅ dispatchEvent — hợp lệ, đây là use case riêng
│   │
│   └── CÓ (click, fill, hover, ...)
│       ├── Test scope là user flow (e2e thật)?
│       │   ├── click() default
│       │   │   ├── PASS → DONE
│       │   │   │
│       │   │   └── FAIL → Đọc message, manual reproduce
│       │   │       ├── User thật cũng gặp → ❌ UI bug — fix UI
│       │   │       │
│       │   │       ├── User OK, lỗi do env CI → fix env (mock service, ...)
│       │   │       │
│       │   │       └── User OK, limit model Playwright (3 case bài 225)
│       │   │           └── force: true + comment đầy đủ
│       │   │
│       │   └── Vẫn FAIL với force (overlay phủ hoàn toàn, ...)?
│       │       ├── App check isTrusted? → ❌ Không thể dispatchEvent — fix UI / mock
│       │       │
│       │       └── App không check → dispatchEvent + comment cảnh báo
│       │
│       └── Test scope là handler logic (integration / unit)?
│           └── ✅ dispatchEvent — chấp nhận trade-off, document rõ
│               (Nên review xem có phải tách thành unit test thì tốt hơn)

Tinh thần decision tree: dispatchEvent không tự nhiên là sai — nhưng cần answer rõ ba câu hỏi trước khi chọn:

Test này là e2e hay handler test? — Nếu handler test, dispatchEvent OK. Nếu e2e, gần như luôn sai.
User có cách trigger event này không? — Nếu không, dispatchEvent là cách duy nhất, OK.
App có check isTrusted hoặc dùng API yêu cầu user activation không? — Nếu có, dispatchEvent không hoạt động.

// Áp dụng decision tree — 4 case thực tế

// Case A: e2e flow checkout — click Submit button
// → User path có (click), e2e scope, không check isTrusted
// → Default: click(). Fail → debug actionability, force chỉ khi limit model.
// → KHÔNG dispatchEvent.
await page.locator('#submit-order').click();

// Case B: integration test analytics handler — verify event tracking
// → Handler test scope, không quan tâm UI hit testing
// → dispatchEvent hợp lệ + comment
await page.locator('[data-testid=cta]').dispatchEvent('click');

// Case C: trigger inventory-update custom event
// → User path KHÔNG có (custom event nội bộ)
// → dispatchEvent là cách duy nhất
await page.locator('html').dispatchEvent('inventory-update', {
  detail: { items: [...] },
  bubbles: true,
});

// Case D: payment confirm flow (Stripe)
// → App check isTrusted để chặn programmatic payment
// → dispatchEvent BỊ REJECT bởi handler
// → Phải dùng click() default hoặc force
await page.locator('#pay-button').click();

14

6 Pitfalls Đóng Nhóm 25

Pitfall 1 — `isTrusted = false` break security check

Handler app check e.isTrusted sẽ return sớm với dispatchEvent. Bug ẩn: test pass (action method không throw), nhưng handler logic không chạy. Khó detect vì không có error message.

// Handler check isTrusted
// document.querySelector('#submit').addEventListener('click', (e) => {
//   if (!e.isTrusted) return; // ← Silent return
//   submitOrder();
// });

await page.locator('#submit').dispatchEvent('click');
// ✅ Action call không throw — Playwright happy
// ❌ submitOrder() KHÔNG chạy
// ❌ Test sau đó expect order created → fail ở step kế tiếp, khó debug ngược

// Fix: dùng click() default — isTrusted = true qua input pipeline
await page.locator('#submit').click();

Pitfall 2 — Bypass pipeline làm test khác production

Test pass với dispatchEvent không nói gì về user thật. Toàn bộ bug UX về tương tác (overlay, hit testing, focus, scroll, disabled) bị che. Đặc biệt nghiêm trọng vì test pipeline tạo cảm giác sai về chất lượng.

// SAI — test pass vì dispatchEvent bypass mọi check UX

await page.locator('.product-card').first().locator('button.add-to-cart').dispatchEvent('click');
await expect(page.locator('[data-testid=cart-count]')).toHaveText('1');
// ✅ Test pass
// ❌ Production: button bị Intercom widget che → user không click được
// ❌ Mobile: button off-screen vì sticky header sai → user không tap được

// ĐÚNG — click() default phát hiện cả hai bug trên
await page.locator('.product-card').first().locator('button.add-to-cart').click();
// → Timeout receives events ở case Intercom
// → Timeout scroll ở case mobile
// → Test fail, dev phát hiện và fix

Pitfall 3 — Custom event không bubble lên listener

Custom event mặc định có bubbles: false nếu không set explicit trong eventInit. Listener đăng ký trên ancestor (document, window, root) không nhận event — handler không chạy nhưng test không báo lỗi.

// App listener trên document
// document.addEventListener('cart-update', (e) => updateUI(e.detail));

// SAI — thiếu bubbles
await page.locator('#cart-icon').dispatchEvent('cart-update', {
  detail: { count: 3 },
  // ❌ bubbles không set → default false → không bubble lên document
});
// ❌ Listener không nhận, updateUI không chạy
// ❌ Test sau đó expect cart count = 3 → fail ngầm

// ĐÚNG
await page.locator('#cart-icon').dispatchEvent('cart-update', {
  detail: { count: 3 },
  bubbles: true,
  cancelable: true,
});

Pitfall 4 — `eventInit` thiếu field handler cần

Handler đọc các property cụ thể của event (clientX, shiftKey, relatedTarget). Init dict thiếu → property mặc định (0, false, null) → handler chạy với input sai, có thể throw hoặc xử lý sai logic.

// Handler dùng clientX để định vị tooltip
// function showTooltip(e: MouseEvent) {
//   tooltip.style.left = e.clientX + 'px';
//   tooltip.style.top = e.clientY + 'px';
// }

// SAI — thiếu clientX/Y
await page.locator('#trigger').dispatchEvent('click');
// → e.clientX = 0, e.clientY = 0
// → Tooltip hiển thị góc trên trái, không phải gần element

// ĐÚNG — set toạ độ thực
const box = await page.locator('#trigger').boundingBox();
await page.locator('#trigger').dispatchEvent('click', {
  clientX: box.x + box.width / 2,
  clientY: box.y + box.height / 2,
  bubbles: true,
});

Pitfall 5 — Bỏ actionability check ẩn missing visible/enabled

dispatchEvent dispatch lên element không visible, disabled, off-screen mà không báo lỗi. Test pass dù element không khả dụng cho user — bug regression không bị catch. Đặc biệt nguy hiểm khi refactor UI làm element ẩn không cố ý.

// Bug refactor: developer accidentally hide element
// .submit-btn { display: none; } // ← bug từ rebase nhầm

// Test với dispatchEvent — không phát hiện
await page.locator('.submit-btn').dispatchEvent('click');
// ✅ Pass vì handler chạy được (element vẫn attached)
// ❌ Production: user không thấy button → không submit được

// Test với click() — phát hiện ngay
await page.locator('.submit-btn').click();
// ❌ Timeout: element is not visible
// → Dev biết để fix CSS bug

Pitfall 6 — Accidentally trigger nhiều event không cần

Một số handler bắt nhiều event (vd analytics tracking trên cả mousedown và click, validation chạy trên input và change). dispatchEvent một event không sinh chuỗi, có thể miss event mà handler dựa vào — ngược lại, fire chuỗi event giả manual có thể trigger thừa.

// Handler trên mousedown + click
// button.addEventListener('mousedown', trackInteraction);
// button.addEventListener('click', submitOrder);

// SAI — chỉ fire click, mousedown miss
await page.locator('#submit').dispatchEvent('click');
// → submitOrder chạy
// → trackInteraction KHÔNG chạy → metric thiếu data

// "Fix" sai — fire cả chuỗi manual, dễ thừa thiếu
await page.locator('#submit').dispatchEvent('mousedown');
await page.locator('#submit').dispatchEvent('mouseup');
await page.locator('#submit').dispatchEvent('click');
// → Cần thêm pointerdown/pointerup không?
// → Cần thêm focus không?
// → Browser tự sinh chuỗi này tốt hơn — đó là lý do dùng click() default

// ĐÚNG — dùng click() để browser xử lý chuỗi event đầy đủ
await page.locator('#submit').click();

15

Tổng Kết Nhóm 25 + Quiz 7 Câu Mix + Bài 229

Tổng Kết Nhóm 25 (12 Bài 217-228)

Triết lý auto-waiting (217-218): Playwright tự đợi element ở trạng thái actionable trước khi action — giảm flakiness, không cần sleep tay. Actionability lifecycle có ba phase: pre-check, action, post-wait.
6 check actionability (219-224): attached (DOM tree), visible (display/visibility/opacity/box), stable (box không đổi 2 frames), enabled (không disabled/aria-disabled), editable (không readonly cho input), receives events (elementFromPoint đúng target).
Actionability matrix (224): bảng đối chiếu action × check — mỗi action method chạy subset check phù hợp (click cần 5 check, hover chỉ cần 3, fill thay enabled bằng editable, ...).
4 escape hatch (225-228):
- force: true — bỏ pre-check actionability, giữ input pipeline browser, isTrusted = true.
- trial: true — chỉ chạy check không dispatch event. Verify "element actionable không".
- noWaitAfter: true — bỏ phase post-wait. Use case popup/download/intermediate state. Đang deprecation trend.
- dispatchEvent() — bỏ pre-check + scroll + input pipeline. Dispatch DOM event qua JS API, isTrusted = false. Custom event, handler test isolated.
Quy tắc chọn escape hatch: nhẹ nhất khả thi. Default click → force (limit model) → dispatchEvent (custom event / handler isolated). Mỗi escape hatch phải có comment giải thích.
Anti-pattern chung: phản xạ "thêm option bypass" khi test fail. Đúng quy trình: đọc message, manual reproduce, phân loại nguyên nhân (UI bug / env / limit model), chỉ escape ở case limit model.
Cảnh báo nghiêm trọng nhất: dispatchEvent ẩn class bug UX cấu trúc (overlay, disabled, focus, visible) — không phát hiện bất kỳ bug tương tác nào. Test pass nghĩa là handler logic đúng, không nói gì về user flow.

Quiz 7 Câu Mix Nội Dung Cả Nhóm 25

Câu 1

Trong lifecycle actionability của Playwright, escape hatch nào tác động vào phase POST-action (wait sau khi dispatch event)?

force: true
trial: true
noWaitAfter: true
dispatchEvent()

Đáp án

C. noWaitAfter: true tác động đúng phase post-action — bỏ qua chờ navigation, scroll, animation hậu quả của action. force tác động phase pre-check (bỏ actionability). trial tác động phase action (không dispatch event). dispatchEvent tác động cả phase pre-check VÀ scroll VÀ post-wait — không chỉ riêng post.

Câu 2

Element ở trạng thái display: none nhưng vẫn trong DOM tree. Câu nào ĐÚNG?

click() default pass vì element vẫn attached.
click({ force: true }) dispatch event qua input pipeline tại toạ độ tâm; box (0,0) có thể trúng element khác.
dispatchEvent('click') luôn fail vì element không visible.
trial: true pass vì chỉ check không thật sự click.

Đáp án

B. Element attached nhưng không visible: click default fail timeout visible check. Force bypass check, dispatch mouse event tại toạ độ — display:none nên box (0,0), event có thể trúng element khác do hit testing. dispatchEvent không quan tâm visible (bypass), event đến đúng target. Trial vẫn chạy check visible → cũng fail giống click default. Vậy chỉ B đúng.

Câu 3

App handler check if (!e.isTrusted) return. Cách nào KHÔNG trigger được handler này?

page.locator('#btn').click()
page.locator('#btn').click({ force: true })
page.locator('#btn').dispatchEvent('click')
page.touchscreen.tap(x, y)

Đáp án

C. dispatchEvent tạo event JS-side (new MouseEvent), browser set isTrusted = false theo chuẩn DOM. Handler return sớm, không chạy. A, B, D đều qua CDP Input.dispatchMouseEvent/Input.dispatchTouchEvent — browser xử lý qua input pipeline nên event có isTrusted = true. Đây là kiến thức Bài 207 áp dụng cho dispatchEvent.

Câu 4

Test cần verify một custom event 'cart-cleared' được app expose qua document.dispatchEvent. Không có button user click trigger. Cách viết test đúng?

Không thể test — Playwright không hỗ trợ custom event.
await page.locator('html').dispatchEvent('cart-cleared', { bubbles: true }) — đúng use case của dispatchEvent.
Tìm cách click hidden button rồi force trigger event qua chain DOM.
Dùng page.evaluate trực tiếp, không qua locator.

Đáp án

B. Custom event không có user gesture tương ứng là một trong ba use case hợp lệ của dispatchEvent. Target html với bubbles: true để event lan tới listener trên document. A sai — Playwright hỗ trợ qua chính method này. C là workaround vô nghĩa. D đúng kỹ thuật nhưng dispatchEvent là API chính thức bao đóng pattern này — đọc rõ intent hơn.

Câu 5

Test fail "element is not stable" trên button có animation pulse infinite (CSS keyframes, design system third-party không thể disable). User click bình thường trên browser thật. Cách xử lý đúng?

dispatchEvent('click') — bypass mọi check.
click({ force: true }) với comment giải thích animation infinite là limit model stable check, đã verify user thật click được.
Tăng timeout lên 60s — animation sớm muộn cũng stable.
trial: true để verify rồi click sau.

Đáp án

B. Đây là case "animation infinite không stable" — một trong 3 case hợp lý dùng force ở góc actionability (Bài 225). Comment phải nêu rõ: check stable fail, animation infinite là limit model Playwright (2 frames identical), đã verify user thật. C sai vì animation infinite không bao giờ stable. A bypass quá mạnh — mất luôn focus + isTrusted, khả năng break handler khác. D không giải quyết — trial chỉ verify, sau đó click cũng fail tương tự.

Câu 6

Phát biểu nào về 4 escape hatch của Nhóm 25 là CHÍNH XÁC?

force và dispatchEvent đều bypass actionability check và đều giữ isTrusted = true.
trial chạy actionability check rồi không dispatch event, dùng để verify "element có actionable không" không có side effect.
noWaitAfter bypass cả actionability check trước action và post-wait sau action.
dispatchEvent nhẹ nhất trong 4 escape hatch, dùng cho mọi click không cần bypass actionability.

Đáp án

B. trial: true đúng là chạy actionability check, không dispatch event, dùng smoke test fail-fast (Bài 226). A sai — force giữ isTrusted = true (qua input pipeline) nhưng dispatchEvent isTrusted = false (JS-created). C sai — noWaitAfter chỉ bỏ post-wait, không bỏ pre-check actionability. D sai — dispatchEvent MẠNH nhất, không phải nhẹ nhất, và là last resort không phải mặc định.

Câu 7

Codebase có 50 chỗ dùng dispatchEvent('click') trong test e2e flow user thật (checkout, login, search). Đánh giá nào ĐÚNG?

Test pass nhanh hơn, hợp lý ưu tiên performance.
Dấu hiệu codebase đã chuyển sang testing handler logic thay vì user flow — toàn bộ class bug UX cấu trúc (overlay, disabled, focus, visible, hit testing) đang bị che. Cần audit và refactor sang click() default.
Pattern chuẩn cho test stable — Playwright khuyến nghị dùng dispatchEvent cho mọi action.
Không vấn đề nếu app không check isTrusted.

Đáp án

B. 50 dispatchEvent trong test e2e là red flag nghiêm trọng. dispatchEvent bypass toàn bộ tầng UX (visible, stable, enabled, hit testing, focus, scroll) — test "pass" không phản ánh user thật. Bug overlay che, button disabled không feedback, mobile off-screen, focus broken — tất cả đi vào production. Cần audit, phân loại từng case: nếu là e2e flow user → refactor sang click(); nếu là handler test → tách thành integration / unit test riêng, không lẫn e2e suite. A, C, D đều sai về nguyên tắc — đặc biệt C, Playwright khuyến nghị ngược lại (dispatchEvent là last resort).

Bài Tiếp Theo — Mở Nhóm 26

Nhóm 25 đóng với 4 escape hatch — đã đi hết phổ bypass auto-waiting từ nhẹ đến nặng. Nhóm 26 chuyển sang chủ đề Explicit Waits — các API waitFor* mà dev tự gọi khi auto-waiting không cover (đợi state cụ thể, đợi network response, đợi function expression evaluate true). Đây là cặp đối ngẫu với Nhóm 25: nhóm trước về cách Playwright tự đợi, nhóm sau về cách dev đợi explicit khi cần thêm.

Bài 229: page.waitForSelector() — API Legacy — mở Nhóm 26 với API explicit wait cũ nhất. Bài trình bày cú pháp waitForSelector(selector, { state }), bốn state value ('attached' / 'detached' / 'visible' / 'hidden'), trạng thái deprecated dần (khuyến nghị dùng locator.waitFor() thay thế), so sánh với pattern locator hiện đại, lý do còn tồn tại trong codebase legacy, và migration path từ waitForSelector sang locator.waitFor.

Thẻ: rest-api

Series liên quan

Django Advanced - Master Level