[Debug API] Add debugging capability

[compulim]

Changelog Entry

Added

• New debug API, by @compulim in PR #5663, see DEBUGGING.md for more
  • Debug into element: open F12, select the subject in Element pane, type $0.webChat.debugger
  • Breakpoint: open F12, select the subject in Element pane, type $0.webChat.breakpoint.incomingActivity

Description

New debug API is added for debuggability.

Design

Debug API

We are introducing a new debug API interface. The new API attach to HTML element directly for debugging.

Currently, 2 types of elements has the debug API attached:

• Root container $('.webchat')
• Activity $('article')

debugger property

Note: this method will not work when Content Security Policy is enabled without script-src unsafe-eval. We do not recommend the policy to be enabled. In such scenario, use the debug() method instead.

The user would trigger the debugger in Web Chat context.

1. Press F12 to open Chrome DevTools
2. In the Elements pane, identify Web Chat root element to debug and click on it
   • Note: the element should have class name of .webchat
3. In console, type $0.webChat.debugger and press ENTER
4. Chrome should break into debugger with debug context in the closure
   • The debug context contains data from Web Chat backend

debug() on published breakpoint

Note: breakpoints are for debugging and may change from time to time.

1. Press F12 to open Chrome DevTools
2. In the Elements pane, identify Web Chat root element to debug and click on it
   • Note: the element should have class name of .webchat
3. In console, type debug($0.webChat.breakpoint.incomingActivity) and press ENTER
4. When a message arrive, Chrome should break into debugger with debug context in the closure

Components and their breakpoints

Component	CSS selector	Breakpoint	Description
Root container	$('.webchat')	incomingActivity	When an activity arrive
Activity row	$('article')	render	When the activity render

To break when an activity arrive, type in DevTools.

debug($('.webchat').webChat.breakpoint.incomingActivity)

Components and their debug context

Component	CSS selector	Debug context	Description
Root container	$('.webchat')	activities	All messages in the chat history
Activity row	$('article')	activity	The current message

Recipes

Break into debugger of the first instance of Web Chat on the page

$('.webchat').webChat.debugger;

Break into debugger of the last activity on the page

$$('article').at(-1).webChat.debugger;

Specific Changes

• Added new debug API to root container and <ActivityRow>
• Added breakpoint and debugger to debug API
• Fixed some flaky tests

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)