feat: Add support for displaying toast-style notifications. (#8896)

* feat: Allow resetting alert/prompt/confirm to defaults. * chore: Add unit tests for Blockly.dialog. * fix: Removed TEST_ONLY hack from Blockly.dialog. * feat: Add a default toast notification implementation. * feat: Add support for toasts to Blockly.dialog. * chore: Add tests for default toast implementation. * chore: Fix docstring. * refactor: Use default arguments for dialog functions. * refactor: Add 'close' to the list of messages. * chore: Add new message in several other places. * chore: clarify docstrings. * feat: Make toast assertiveness configurable.
2025-12-16 06:10:12 +01:00 · 2025-04-21 15:32:45 -07:00
parent 9d127698d6
commit c6e58c4f92
12 changed files with 620 additions and 46 deletions
--- a/core/blockly.ts
+++ b/core/blockly.ts
@@ -432,6 +432,8 @@ Names.prototype.populateProcedures = function (
 };
 // clang-format on

+export * from './toast.js';
+
 // Re-export submodules that no longer declareLegacyNamespace.
 export {
  ASTNode,
--- a/core/dialog.ts
+++ b/core/dialog.ts
@@ -6,24 +6,29 @@

 // Former goog.module ID: Blockly.dialog

-let alertImplementation = function (
-  message: string,
-  opt_callback?: () => void,
-) {
+import type {ToastOptions} from './toast.js';
+import {Toast} from './toast.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+const defaultAlert = function (message: string, opt_callback?: () => void) {
  window.alert(message);
  if (opt_callback) {
    opt_callback();
  }
 };

-let confirmImplementation = function (
+let alertImplementation = defaultAlert;
+
+const defaultConfirm = function (
  message: string,
  callback: (result: boolean) => void,
 ) {
  callback(window.confirm(message));
 };

-let promptImplementation = function (
+let confirmImplementation = defaultConfirm;
+
+const defaultPrompt = function (
  message: string,
  defaultValue: string,
  callback: (result: string | null) => void,
@@ -31,6 +36,11 @@ let promptImplementation = function (
  callback(window.prompt(message, defaultValue));
 };

+let promptImplementation = defaultPrompt;
+
+const defaultToast = Toast.show.bind(Toast);
+let toastImplementation = defaultToast;
+
 /**
 * Wrapper to window.alert() that app developers may override via setAlert to
 * provide alternatives to the modal browser window.
@@ -45,10 +55,16 @@ export function alert(message: string, opt_callback?: () => void) {
 /**
 * Sets the function to be run when Blockly.dialog.alert() is called.
 *
- * @param alertFunction The function to be run.
+ * @param alertFunction The function to be run, or undefined to restore the
+ *     default implementation.
 * @see Blockly.dialog.alert
 */
-export function setAlert(alertFunction: (p1: string, p2?: () => void) => void) {
+export function setAlert(
+  alertFunction: (
+    message: string,
+    callback?: () => void,
+  ) => void = defaultAlert,
+) {
  alertImplementation = alertFunction;
 }

@@ -59,25 +75,22 @@ export function setAlert(alertFunction: (p1: string, p2?: () => void) => void) {
 * @param message The message to display to the user.
 * @param callback The callback for handling user response.
 */
-export function confirm(message: string, callback: (p1: boolean) => void) {
-  TEST_ONLY.confirmInternal(message, callback);
-}
-
-/**
- * Private version of confirm for stubbing in tests.
- */
-function confirmInternal(message: string, callback: (p1: boolean) => void) {
+export function confirm(message: string, callback: (result: boolean) => void) {
  confirmImplementation(message, callback);
 }

 /**
 * Sets the function to be run when Blockly.dialog.confirm() is called.
 *
- * @param confirmFunction The function to be run.
+ * @param confirmFunction The function to be run, or undefined to restore the
+ *     default implementation.
 * @see Blockly.dialog.confirm
 */
 export function setConfirm(
-  confirmFunction: (p1: string, p2: (p1: boolean) => void) => void,
+  confirmFunction: (
+    message: string,
+    callback: (result: boolean) => void,
+  ) => void = defaultConfirm,
 ) {
  confirmImplementation = confirmFunction;
 }
@@ -95,7 +108,7 @@ export function setConfirm(
 export function prompt(
  message: string,
  defaultValue: string,
-  callback: (p1: string | null) => void,
+  callback: (result: string | null) => void,
 ) {
  promptImplementation(message, defaultValue, callback);
 }
@@ -103,19 +116,45 @@ export function prompt(
 /**
 * Sets the function to be run when Blockly.dialog.prompt() is called.
 *
- * @param promptFunction The function to be run.
+ * @param promptFunction The function to be run, or undefined to restore the
+ *     default implementation.
 * @see Blockly.dialog.prompt
 */
 export function setPrompt(
  promptFunction: (
-    p1: string,
-    p2: string,
-    p3: (p1: string | null) => void,
-  ) => void,
+    message: string,
+    defaultValue: string,
+    callback: (result: string | null) => void,
+  ) => void = defaultPrompt,
 ) {
  promptImplementation = promptFunction;
 }

-export const TEST_ONLY = {
-  confirmInternal,
-};
+/**
+ * Displays a temporary notification atop the workspace. Blockly provides a
+ * default toast implementation, but developers may provide their own via
+ * setToast. For simple appearance customization, CSS should be sufficient.
+ *
+ * @param workspace The workspace to display the toast notification atop.
+ * @param options Configuration options for the notification, including its
+ *     message and duration.
+ */
+export function toast(workspace: WorkspaceSvg, options: ToastOptions) {
+  toastImplementation(workspace, options);
+}
+
+/**
+ * Sets the function to be run when Blockly.dialog.toast() is called.
+ *
+ * @param toastFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.toast
+ */
+export function setToast(
+  toastFunction: (
+    workspace: WorkspaceSvg,
+    options: ToastOptions,
+  ) => void = defaultToast,
+) {
+  toastImplementation = toastFunction;
+}
--- a/core/toast.ts
+++ b/core/toast.ts
@@ -0,0 +1,219 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Css from './css.js';
+import {Msg} from './msg.js';
+import * as aria from './utils/aria.js';
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+const CLASS_NAME = 'blocklyToast';
+const MESSAGE_CLASS_NAME = 'blocklyToastMessage';
+const CLOSE_BUTTON_CLASS_NAME = 'blocklyToastCloseButton';
+
+/**
+ * Display/configuration options for a toast notification.
+ */
+export interface ToastOptions {
+  /**
+   * Toast ID. If set along with `oncePerSession`, will cause subsequent toasts
+   * with this ID to not be shown.
+   */
+  id?: string;
+
+  /**
+   * Flag to show the toast once per session only.
+   * Subsequent calls are ignored.
+   */
+  oncePerSession?: boolean;
+
+  /**
+   * Text of the message to display on the toast.
+   */
+  message: string;
+
+  /**
+   * Duration in seconds before the toast is removed. Defaults to 5.
+   */
+  duration?: number;
+
+  /**
+   * How prominently/interrupting the readout of the toast should be for
+   * screenreaders. Corresponds to aria-live and defaults to polite.
+   */
+  assertiveness?: Toast.Assertiveness;
+}
+
+/**
+ * Class that allows for showing and dismissing temporary notifications.
+ */
+export class Toast {
+  /** IDs of toasts that have previously been shown. */
+  private static shownIds = new Set<string>();
+
+  /**
+   * Shows a toast notification.
+   *
+   * @param workspace The workspace to show the toast on.
+   * @param options Configuration options for the toast message, duration, etc.
+   */
+  static show(workspace: WorkspaceSvg, options: ToastOptions) {
+    if (options.oncePerSession && options.id) {
+      if (this.shownIds.has(options.id)) return;
+      this.shownIds.add(options.id);
+    }
+
+    // Clear any existing toasts.
+    this.hide(workspace);
+
+    const toast = this.createDom(workspace, options);
+
+    // Animate the toast into view.
+    requestAnimationFrame(() => {
+      toast.style.bottom = '2rem';
+    });
+  }
+
+  /**
+   * Creates the DOM representation of a toast.
+   *
+   * @param workspace The workspace to inject the toast notification onto.
+   * @param options Configuration options for the toast.
+   * @returns The root DOM element of the toast.
+   */
+  protected static createDom(workspace: WorkspaceSvg, options: ToastOptions) {
+    const {
+      message,
+      duration = 5,
+      assertiveness = Toast.Assertiveness.POLITE,
+    } = options;
+
+    const toast = document.createElement('div');
+    workspace.getInjectionDiv().appendChild(toast);
+    toast.dataset.toastId = options.id;
+    toast.className = CLASS_NAME;
+    aria.setRole(toast, aria.Role.STATUS);
+    aria.setState(toast, aria.State.LIVE, assertiveness);
+
+    const messageElement = toast.appendChild(document.createElement('div'));
+    messageElement.className = MESSAGE_CLASS_NAME;
+    messageElement.innerText = message;
+    const closeButton = toast.appendChild(document.createElement('button'));
+    closeButton.className = CLOSE_BUTTON_CLASS_NAME;
+    aria.setState(closeButton, aria.State.LABEL, Msg['CLOSE']);
+    const closeIcon = dom.createSvgElement(
+      Svg.SVG,
+      {
+        width: 24,
+        height: 24,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+      },
+      closeButton,
+    );
+    aria.setState(closeIcon, aria.State.HIDDEN, true);
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        x: 19.7782,
+        y: 2.80762,
+        width: 2,
+        height: 24,
+        transform: 'rotate(45, 19.7782, 2.80762)',
+        fill: 'black',
+      },
+      closeIcon,
+    );
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        x: 2.80762,
+        y: 4.22183,
+        width: 2,
+        height: 24,
+        transform: 'rotate(-45, 2.80762, 4.22183)',
+        fill: 'black',
+      },
+      closeIcon,
+    );
+    closeButton.addEventListener('click', () => {
+      toast.remove();
+      workspace.markFocused();
+    });
+
+    let timeout: ReturnType<typeof setTimeout>;
+    const setToastTimeout = () => {
+      timeout = setTimeout(() => toast.remove(), duration * 1000);
+    };
+    const clearToastTimeout = () => clearTimeout(timeout);
+    toast.addEventListener('focusin', clearToastTimeout);
+    toast.addEventListener('focusout', setToastTimeout);
+    toast.addEventListener('mouseenter', clearToastTimeout);
+    toast.addEventListener('mousemove', clearToastTimeout);
+    toast.addEventListener('mouseleave', setToastTimeout);
+    setToastTimeout();
+
+    return toast;
+  }
+
+  /**
+   * Dismiss a toast, e.g. in response to a user action.
+   *
+   * @param workspace The workspace to dismiss a toast in.
+   * @param id The toast ID, or undefined to clear any toast.
+   */
+  static hide(workspace: WorkspaceSvg, id?: string) {
+    const toast = workspace.getInjectionDiv().querySelector(`.${CLASS_NAME}`);
+    if (toast instanceof HTMLElement && (!id || id === toast.dataset.toastId)) {
+      toast.remove();
+    }
+  }
+}
+
+/**
+ * Options for how aggressively toasts should be read out by screenreaders.
+ * Values correspond to those for aria-live.
+ */
+export namespace Toast {
+  export enum Assertiveness {
+    ASSERTIVE = 'assertive',
+    POLITE = 'polite',
+  }
+}
+
+Css.register(`
+.${CLASS_NAME} {
+  font-size: 1.2rem;
+  position: absolute;
+  bottom: -10rem;
+  right: 2rem;
+  padding: 1rem;
+  color: black;
+  background-color: white;
+  border: 2px solid black;
+  border-radius: 0.4rem;
+  z-index: 999;
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  line-height: 1.5;
+  transition: bottom 0.3s ease-out;
+}
+
+.${CLASS_NAME} .${MESSAGE_CLASS_NAME} {
+  maxWidth: 18rem;
+}
+
+.${CLASS_NAME} .${CLOSE_BUTTON_CLASS_NAME} {
+  margin: 0;
+  padding: 0.2rem;
+  background-color: transparent;
+  color: black;
+  border: none;
+  cursor: pointer;
+}
+`);
--- a/core/utils/aria.ts
+++ b/core/utils/aria.ts
@@ -51,6 +51,9 @@ export enum Role {

  // ARIA role for a visual separator in e.g. a menu.
  SEPARATOR = 'separator',
+
+  // ARIA role for a live region providing information.
+  STATUS = 'status',
 }

 /**
@@ -110,6 +113,14 @@ export enum State {

  // ARIA property for slider minimum value. Value: number.
  VALUEMIN = 'valuemin',
+
+  // ARIA property for live region chattiness.
+  // Value: one of {polite, assertive, off}.
+  LIVE = 'live',
+
+  // ARIA property for removing elements from the accessibility tree.
+  // Value: one of {true, false, undefined}.
+  HIDDEN = 'hidden',
 }

 /**
--- a/msg/json/en.json
+++ b/msg/json/en.json
@@ -18,6 +18,7 @@
 	"DELETE_X_BLOCKS": "Delete %1 Blocks",
 	"DELETE_ALL_BLOCKS": "Delete all %1 blocks?",
 	"CLEAN_UP": "Clean up Blocks",
+	"CLOSE": "Close",
 	"COLLAPSE_BLOCK": "Collapse Block",
 	"COLLAPSE_ALL": "Collapse Blocks",
 	"EXPAND_BLOCK": "Expand Block",
--- a/msg/json/qqq.json
+++ b/msg/json/qqq.json
@@ -24,6 +24,7 @@
 	"DELETE_X_BLOCKS": "context menu - Permanently delete the %1 selected blocks.\n\nParameters:\n* %1 - an integer greater than 1.",
 	"DELETE_ALL_BLOCKS": "confirmation prompt - Question the user if they really wanted to permanently delete all %1 blocks.\n\nParameters:\n* %1 - an integer greater than 1.",
 	"CLEAN_UP": "context menu - Reposition all the blocks so that they form a neat line.",
+	"CLOSE": "toast notification - Accessibility label for close button.",
 	"COLLAPSE_BLOCK": "context menu - Make the appearance of the selected block smaller by hiding some information about it.",
 	"COLLAPSE_ALL": "context menu - Make the appearance of all blocks smaller by hiding some information about it.  Use the same terminology as in the previous message.",
 	"EXPAND_BLOCK": "context menu - Restore the appearance of the selected block by showing information about it that was hidden (collapsed) earlier.",
--- a/msg/messages.js
+++ b/msg/messages.js
@@ -103,6 +103,9 @@ Blockly.Msg.DELETE_ALL_BLOCKS = 'Delete all %1 blocks?';
 /// context menu - Reposition all the blocks so that they form a neat line.
 Blockly.Msg.CLEAN_UP = 'Clean up Blocks';
 /** @type {string} */
+/// toast notification - Accessibility label for close button.
+Blockly.Msg.CLOSE = 'Close';
+/** @type {string} */
 /// context menu - Make the appearance of the selected block smaller by hiding some information about it.
 Blockly.Msg.COLLAPSE_BLOCK = 'Collapse Block';
 /** @type {string} */
--- a/tests/mocha/contextmenu_items_test.js
+++ b/tests/mocha/contextmenu_items_test.js
@@ -318,9 +318,7 @@ suite('Context Menu Items', function () {

      test('Deletes all blocks after confirming', function () {
        // Mocks the confirmation dialog and calls the callback with 'true' simulating ok.
-        const confirmStub = sinon
-          .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-          .callsArgWith(1, true);
+        const confirmStub = sinon.stub(window, 'confirm').returns(true);

        this.workspace.newBlock('text');
        this.workspace.newBlock('text');
@@ -328,13 +326,13 @@ suite('Context Menu Items', function () {
        this.clock.runAll();
        sinon.assert.calledOnce(confirmStub);
        assert.equal(this.workspace.getTopBlocks(false).length, 0);
+
+        confirmStub.restore();
      });

      test('Does not delete blocks if not confirmed', function () {
        // Mocks the confirmation dialog and calls the callback with 'false' simulating cancel.
-        const confirmStub = sinon
-          .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-          .callsArgWith(1, false);
+        const confirmStub = sinon.stub(window, 'confirm').returns(false);

        this.workspace.newBlock('text');
        this.workspace.newBlock('text');
@@ -342,19 +340,20 @@ suite('Context Menu Items', function () {
        this.clock.runAll();
        sinon.assert.calledOnce(confirmStub);
        assert.equal(this.workspace.getTopBlocks(false).length, 2);
+
+        confirmStub.restore();
      });

      test('No dialog for single block', function () {
-        const confirmStub = sinon.stub(
-          Blockly.dialog.TEST_ONLY,
-          'confirmInternal',
-        );
+        const confirmStub = sinon.stub(window, 'confirm');
        this.workspace.newBlock('text');
        this.deleteOption.callback(this.scope);
        this.clock.runAll();

        sinon.assert.notCalled(confirmStub);
        assert.equal(this.workspace.getTopBlocks(false).length, 0);
+
+        confirmStub.restore();
      });

      test('Has correct label for multiple blocks', function () {
--- a/tests/mocha/dialog_test.js
+++ b/tests/mocha/dialog_test.js
@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../node_modules/chai/chai.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('Dialog utilities', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+    this.workspace = Blockly.inject('blocklyDiv', {});
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+    Blockly.dialog.setAlert();
+    Blockly.dialog.setPrompt();
+    Blockly.dialog.setConfirm();
+    Blockly.dialog.setToast();
+  });
+
+  test('use the browser alert by default', function () {
+    const alert = sinon.stub(window, 'alert');
+    Blockly.dialog.alert('test');
+    assert.isTrue(alert.calledWith('test'));
+    alert.restore();
+  });
+
+  test('support setting a custom alert handler', function () {
+    const alert = sinon.spy();
+    Blockly.dialog.setAlert(alert);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.alert(message, callback);
+    assert.isTrue(alert.calledWith('test', callback));
+  });
+
+  test('do not call the browser alert if a custom alert handler is set', function () {
+    const browserAlert = sinon.stub(window, 'alert');
+
+    const alert = sinon.spy();
+    Blockly.dialog.setAlert(alert);
+    Blockly.dialog.alert(test);
+    assert.isFalse(browserAlert.called);
+
+    browserAlert.restore();
+  });
+
+  test('use the browser confirm by default', function () {
+    const confirm = sinon.stub(window, 'confirm');
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(confirm.calledWith(message));
+    confirm.restore();
+  });
+
+  test('support setting a custom confirm handler', function () {
+    const confirm = sinon.spy();
+    Blockly.dialog.setConfirm(confirm);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(confirm.calledWith('test', callback));
+  });
+
+  test('do not call the browser confirm if a custom confirm handler is set', function () {
+    const browserConfirm = sinon.stub(window, 'confirm');
+
+    const confirm = sinon.spy();
+    Blockly.dialog.setConfirm(confirm);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isFalse(browserConfirm.called);
+
+    browserConfirm.restore();
+  });
+
+  test('invokes the provided callback with the confirmation response', function () {
+    const confirm = sinon.stub(window, 'confirm').returns(true);
+    const callback = sinon.spy();
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(callback.calledWith(true));
+    confirm.restore();
+  });
+
+  test('use the browser prompt by default', function () {
+    const prompt = sinon.stub(window, 'prompt');
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(prompt.calledWith(message, defaultValue));
+    prompt.restore();
+  });
+
+  test('support setting a custom prompt handler', function () {
+    const prompt = sinon.spy();
+    Blockly.dialog.setPrompt(prompt);
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(prompt.calledWith('test', defaultValue, callback));
+  });
+
+  test('do not call the browser prompt if a custom prompt handler is set', function () {
+    const browserPrompt = sinon.stub(window, 'prompt');
+
+    const prompt = sinon.spy();
+    Blockly.dialog.setPrompt(prompt);
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isFalse(browserPrompt.called);
+
+    browserPrompt.restore();
+  });
+
+  test('invokes the provided callback with the prompt response', function () {
+    const prompt = sinon.stub(window, 'prompt').returns('something');
+    const callback = sinon.spy();
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(callback.calledWith('something'));
+    prompt.restore();
+  });
+
+  test('use the built-in toast by default', function () {
+    const message = 'test toast';
+    Blockly.dialog.toast(this.workspace, {message});
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+    assert.isNotNull(toast);
+    assert.equal(toast.textContent, message);
+  });
+
+  test('support setting a custom toast handler', function () {
+    const toast = sinon.spy();
+    Blockly.dialog.setToast(toast);
+    const message = 'test toast';
+    const options = {message};
+    Blockly.dialog.toast(this.workspace, options);
+    assert.isTrue(toast.calledWith(this.workspace, options));
+  });
+
+  test('do not use the built-in toast if a custom toast handler is set', function () {
+    const builtInToast = sinon.stub(Blockly.Toast, 'show');
+
+    const toast = sinon.spy();
+    Blockly.dialog.setToast(toast);
+    const message = 'test toast';
+    Blockly.dialog.toast(this.workspace, {message});
+    assert.isFalse(builtInToast.called);
+
+    builtInToast.restore();
+  });
+});
--- a/tests/mocha/index.html
+++ b/tests/mocha/index.html
@@ -192,6 +192,7 @@
      import './contextmenu_items_test.js';
      import './contextmenu_test.js';
      import './cursor_test.js';
+      import './dialog_test.js';
      import './dropdowndiv_test.js';
      import './event_test.js';
      import './event_block_change_test.js';
@@ -260,6 +261,7 @@
      import './shortcut_registry_test.js';
      import './touch_test.js';
      import './theme_test.js';
+      import './toast_test.js';
      import './toolbox_test.js';
      import './tooltip_test.js';
      import './trashcan_test.js';
--- a/tests/mocha/test_helpers/workspace.js
+++ b/tests/mocha/test_helpers/workspace.js
@@ -100,9 +100,7 @@ export function testAWorkspace() {

    test('deleteVariableById(id2) one usage', function () {
      // Deleting variable one usage should not trigger confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, true);
+      const stub = sinon.stub(window, 'confirm').returns(true);
      this.workspace.deleteVariableById('id2');

      sinon.assert.notCalled(stub);
@@ -110,13 +108,13 @@ export function testAWorkspace() {
      assert.isNull(variable);
      assertVariableValues(this.workspace, 'name1', 'type1', 'id1');
      assertBlockVarModelName(this.workspace, 0, 'name1');
+
+      stub.restore();
    });

    test('deleteVariableById(id1) multiple usages confirm', function () {
      // Deleting variable with multiple usages triggers confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, true);
+      const stub = sinon.stub(window, 'confirm').returns(true);
      this.workspace.deleteVariableById('id1');

      sinon.assert.calledOnce(stub);
@@ -124,13 +122,13 @@ export function testAWorkspace() {
      assert.isNull(variable);
      assertVariableValues(this.workspace, 'name2', 'type2', 'id2');
      assertBlockVarModelName(this.workspace, 0, 'name2');
+
+      stub.restore();
    });

    test('deleteVariableById(id1) multiple usages cancel', function () {
      // Deleting variable with multiple usages triggers confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, false);
+      const stub = sinon.stub(window, 'confirm').returns(false);
      this.workspace.deleteVariableById('id1');

      sinon.assert.calledOnce(stub);
@@ -139,6 +137,8 @@ export function testAWorkspace() {
      assertBlockVarModelName(this.workspace, 0, 'name1');
      assertBlockVarModelName(this.workspace, 1, 'name1');
      assertBlockVarModelName(this.workspace, 2, 'name2');
+
+      stub.restore();
    });
  });

--- a/tests/mocha/toast_test.js
+++ b/tests/mocha/toast_test.js
@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../node_modules/chai/chai.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('Toasts', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+    this.workspace = Blockly.inject('blocklyDiv', {});
+    this.toastIsVisible = (message) => {
+      const toast = this.workspace
+        .getInjectionDiv()
+        .querySelector('.blocklyToast');
+      return !!(toast && toast.textContent === message);
+    };
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+  });
+
+  test('can be shown', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message});
+    assert.isTrue(this.toastIsVisible(message));
+  });
+
+  test('can be shown only once per session', function () {
+    const options = {
+      message: 'texas toast',
+      id: 'test',
+      oncePerSession: true,
+    };
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+    Blockly.Toast.hide(this.workspace);
+    Blockly.Toast.show(this.workspace, options);
+    assert.isFalse(this.toastIsVisible(options.message));
+  });
+
+  test('oncePerSession is ignored when false', function () {
+    const options = {
+      message: 'texas toast',
+      id: 'some id',
+      oncePerSession: true,
+    };
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+    Blockly.Toast.hide(this.workspace);
+    options.oncePerSession = false;
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+  });
+
+  test('can be hidden', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace);
+    assert.isFalse(this.toastIsVisible(message));
+  });
+
+  test('can be hidden by ID', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace, 'test');
+    assert.isFalse(this.toastIsVisible(message));
+  });
+
+  test('hide does not hide toasts with different ID', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace, 'test2');
+    assert.isTrue(this.toastIsVisible(message));
+  });
+
+  test('are shown for the designated duration', function () {
+    const clock = sinon.useFakeTimers();
+
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, duration: 3});
+    for (let i = 0; i < 3; i++) {
+      assert.isTrue(this.toastIsVisible(message));
+      clock.tick(1000);
+    }
+    assert.isFalse(this.toastIsVisible(message));
+
+    clock.restore();
+  });
+
+  test('default to polite assertiveness', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+
+    assert.equal(
+      toast.getAttribute('aria-live'),
+      Blockly.Toast.Assertiveness.POLITE,
+    );
+  });
+
+  test('respects assertiveness option', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {
+      message,
+      id: 'test',
+      assertiveness: Blockly.Toast.Assertiveness.ASSERTIVE,
+    });
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+
+    assert.equal(
+      toast.getAttribute('aria-live'),
+      Blockly.Toast.Assertiveness.ASSERTIVE,
+    );
+  });
+});