keymanapp · ermshiperete · May 29, 2026 · Jun 29, 2026 · mcdurdin · Jun 29, 2026
diff --git a/web/build.sh b/web/build.sh
@@ -114,6 +114,25 @@ build_tests_action() {
 
   cp "${KEYMAN_ROOT}/web/src/test/auto/dom/cases/attachment/textStoreForElement.tests.html" \
     "${KEYMAN_ROOT}/web/build/test/dom/cases/attachment/"
+
+  # Copy and update guide examples - for local, PR, and test builds we
+  # replace the CDN URL with the local build path, so that we can test
+  # against the current build
+  mkdir -p "${KEYMAN_ROOT}/web/build/docs/engine/guide"
+  cp -r "${KEYMAN_ROOT}/web/docs/engine/guide/examples" \
+    "${KEYMAN_ROOT}/web/build/docs/engine/guide/"
+
+  # shellcheck disable=SC2310
+  if ! builder_is_ci_release_build; then
+    for f in "${KEYMAN_ROOT}/web/build/docs/engine/guide/examples"/*.html; do
+      # Replace CDN URL (https://s.keyman.com/kwm/engine/18.0.123) with
+      # local local build path (/build/publish/debug). We write to a temp
+      # file and then replace the original instead of modifying in-place.
+      # This is safer and more portable.
+      sed "s|https://s\.keyman\.com/kmw/engine/[0-9]*\.[0-9]*\.[0-9]*/|/build/publish/${config}/|g" \
+        "${f}" > "${f}.tmp" && mv "${f}.tmp" "${f}"
+    done
+  fi
 }
 
 coverage_action() {

diff --git a/web/docs/engine/guide/examples/__auto-control.html b/web/docs/engine/guide/examples/__auto-control.html
@@ -19,8 +19,8 @@
 <body>
 <h1>Automatic Mode Example</h1>
 <form action='.' method='post'>
-<p><input type='text' id='multilingual' name='multilingual' size="40" /></p>
-<p><textarea cols='40' rows='5'></textarea></p>
+<p><input type='text' id='multilingual' name='multilingual' size="40" data-testid='multilingual'/></p>
+<p><textarea cols='40' rows='5' data-testid='textarea'></textarea></p>
 </form>
 
 <a href="automatic-control">Back to Document</a>

diff --git a/web/docs/engine/guide/examples/__full-manual-control.html b/web/docs/engine/guide/examples/__full-manual-control.html
@@ -24,13 +24,13 @@
   }
   document.f.multilingual.focus();
 
-  keyman.setActiveKeyboard('', '');
+  await keyman.setActiveKeyboard('', '');
 });
 
-function KWControlChange() {
+async function KWControlChange() {
   var name = KWControl.value.substr(0, KWControl.value.indexOf("$$"));
   var languageCode = KWControl.value.substr(KWControl.value.indexOf("$$") + 2);
-  keyman.setActiveKeyboard(name, languageCode);
+  await keyman.setActiveKeyboard(name, languageCode);
   document.f.multilingual.focus();
 }
 
@@ -40,7 +40,7 @@
 <h1>Manual Control - Custom Interface</h1>
 <form name='f' action='.' method='post'>
 
-  <p>Keyboard: <select id='KWControl' onchange='KWControlChange()'><option value=''>English</option></select></p>
+  <p><label for='KWControl'>Keyboard:</label> <select id='KWControl' onchange='KWControlChange()'><option value=''>English</option></select></p>
 
 <p><input type='text' id='multilingual' name='multilingual' size="40" placeholder="id='multilingual'"/></p>
 </form>

diff --git a/web/docs/engine/guide/examples/__manual-control.html b/web/docs/engine/guide/examples/__manual-control.html
@@ -11,7 +11,7 @@
         languages: { id: 'lo', name: 'Lao' },
         filename: "./js/laokeys.js"
       });
-      keyman.setActiveKeyboard('laokeys');
+      await keyman.setActiveKeyboard('laokeys');
       keyman.osk.hide();
     });
 
@@ -30,8 +30,8 @@ <h1>Manual Mode Example</h1>
 
 <p><img style="border: solid 1px black; padding: 2px 2px 3px 2px" src='js/kmicon.png' alt='KeymanWeb' onclick='KWControlClick()' id='KWControl' /></p>
 
-<p><input type='text' id='multilingual' name='multilingual' size="40" /></p>
-<p><textarea cols='40' rows='5'></textarea></p>
+<p><input type='text' id='multilingual' name='multilingual' size="40" data-testid='multilingual'/></p>
+<p><textarea cols='40' rows='5' data-testid='textarea'></textarea></p>
 
 <a href="manual-control">Back to Document</a>
 </form>

diff --git a/web/docs/engine/guide/examples/full-manual-control.md b/web/docs/engine/guide/examples/full-manual-control.md
@@ -28,15 +28,15 @@ Include the following script in the HEAD of your page:
     }
     document.f.multilingual.focus();
 
-    keyman.setActiveKeyboard('', '');
+    await keyman.setActiveKeyboard('', '');
   });
 
   /* KWControlChange: Called when user selects an item in the KWControl SELECT */
-  function KWControlChange() {
+  async function KWControlChange() {
     /* Select the keyboard in KeymanWeb */
     var name = KWControl.value.substr(0, KWControl.value.indexOf("$$"));
-    var languageCode = KWControl.value.substr(KWControl.value.indexOf("$$"+2));
-    keyman.setActiveKeyboard(name, languageCode);
+    var languageCode = KWControl.value.substr(KWControl.value.indexOf("$$") + 2);
+    await keyman.setActiveKeyboard(name, languageCode);
     /* Focus onto the multilingual field in the form */
     document.f.multilingual.focus();
   }

diff --git a/web/docs/engine/guide/examples/manual-control.md b/web/docs/engine/guide/examples/manual-control.md
@@ -2,7 +2,10 @@
 title: Manual Mode Example
 ---
 
-In this example, the web page designer specifies when KeymanWeb's on-screen keyboard may be displayed on non-mobile devices. They have also specified that the LaoKeys keyboard should be activated by default. This example continues to use the KeymanWeb default interface. Please click [this link](__manual-control.html) to open the test page.
+In this example, the web page designer specifies when KeymanWeb's on-screen keyboard may be
+displayed on non-mobile devices. They have also specified that the LaoKeys keyboard should be
+activated by default. This example continues to use the KeymanWeb default interface. Please click
+[this link](__manual-control.html) to open the test page.
 
 ## Code Walkthrough
 
@@ -17,7 +20,7 @@ Include the following script in the HEAD of your page:
         languages:{id:'lo',name:'Lao'},
         filename: "./js/laokeys.js"
       });
-      keyman.setActiveKeyboard('laokeys');
+      await keyman.setActiveKeyboard('laokeys');
       keyman.osk.hide();
     });
 

diff --git a/web/src/test/auto/e2e/e2eUtils.ts b/web/src/test/auto/e2e/e2eUtils.ts
@@ -0,0 +1,64 @@
+/*
+ * Keyman is copyright (C) SIL Global. MIT License.
+ */
+
+import { type Locator, type Page } from "@playwright/test";
+
+/**
+ * Expands the keyboard selection menu and returns the text content of the
+ * currently selected keyboard.
+ */
+export async function getSelectedKeyboardMenuText(page: Page): Promise<string | undefined> {
+  const watchDog = page.waitForFunction(() => !!document.getElementById('KeymanWeb_KbdList'));
+  await page.getByRole('img', { name: 'Use Web Keyboard' }).click();
+  await watchDog;
+  return page.evaluate(() => {
+    const selectedKbd = document.querySelector('#kmwico .selected');
+    return selectedKbd?.textContent;
+  });
+};
+
+/**
+ * Expands the keyboard selection menu and returns the menu items as an array
+ */
+export async function getAllKeyboardMenuText(page: Page): Promise<(string|undefined)[]> {
+  const watchDog = page.waitForFunction(() => !!document.getElementById('KeymanWeb_KbdList'));
+  await page.getByRole('img', { name: 'Use Web Keyboard' }).hover();
+  await watchDog;
+  return page.evaluate(() => {
+    const menuItems = [];
+    const menuDiv = document.querySelector('#kmwico');
+    const kbdList = menuDiv?.lastElementChild;
+    for (let i = 0; i < (kbdList ? kbdList.children.length : 0); i++) {
+      const item = kbdList?.children[i];
+      menuItems.push(item?.textContent);
+    }
+    return menuItems;
+  });
+}
+
+/**
+ * Loads the specified URL and waits for the page load event.
+ */
+export async function loadPage(page: Page, url: string): Promise<Page> {
+  const loadPromise = page.waitForEvent('load');
+  await page.goto(url);
+  return loadPromise;
+}
+
+/**
+ * Clicks the specified field and waits for the OSK to be shown, returning a
+ * locator for the OSK title bar.
+ */
+export async function clickFieldAndWaitForOSK(page: Page, fieldLocator: Locator): Promise<Locator> {
+  const keyboardchangePromise = page.evaluate(async () => {
+    return new Promise((resolve) => {
+      keyman.addEventListener('keyboardchange', function (kbd) {
+        resolve(kbd);
+      });
+    });
+  });
+  await fieldLocator.click();
+  await keyboardchangePromise;
+  return page.locator('#keymanweb_title_bar');
+}