From 064e5b4d4b6c08d54cb4dcf167a824fe115b23ce Mon Sep 17 00:00:00 2001
From: Caleb Eby <calebeby@users.noreply.github.com>
Date: Wed, 24 Mar 2021 17:38:06 -0700
Subject: [PATCH] Add user.type and refactor user API (#48)

---
 .changeset/forty-mugs-laugh.md   |   6 +
 README.md                        |  72 +++++++-
 jest.config.js                   |   1 +
 rollup.config.js                 |   2 +
 src/index.ts                     |  12 +-
 src/user-util/index.ts           |  65 +++++++
 src/user-util/rollup.config.js   |  18 ++
 src/user.ts                      | 286 +++++++++++++++++++++++++------
 src/utils.ts                     |  10 +-
 src/vite-server.ts               |   2 +
 tests/forgot-await.test.ts       |  22 ++-
 tests/user/actionability.test.ts | 156 +++++++++++++++++
 tests/user/click.test.ts         |  69 +++++++-
 tests/user/type.test.ts          | 216 +++++++++++++++++++++++
 14 files changed, 864 insertions(+), 73 deletions(-)
 create mode 100644 .changeset/forty-mugs-laugh.md
 create mode 100644 src/user-util/index.ts
 create mode 100644 src/user-util/rollup.config.js
 create mode 100644 tests/user/actionability.test.ts
 create mode 100644 tests/user/type.test.ts

diff --git a/.changeset/forty-mugs-laugh.md b/.changeset/forty-mugs-laugh.md
new file mode 100644
index 00000000..28857a26
--- /dev/null
+++ b/.changeset/forty-mugs-laugh.md
@@ -0,0 +1,6 @@
+---
+'test-mule': minor
+---
+
+- Add user.type method
+- Add actionability checks: visible and attached
diff --git a/README.md b/README.md
index 0fd1d9ec..b5d03f65 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@ Test Mule is driven by these goals:
   - [Making Assertions](#making-assertions)
   - [Performing Actions](#performing-actions)
   - [Troubleshooting/Debugging a Failing Test](#troubleshootingdebugging-a-failing-test)
+  - [Actionability](#actionability)
 - [Full Example](#full-example)
 - [API](#api)
   - [`withBrowser`](#withbrowser)
@@ -261,6 +262,29 @@ test(
 );
 ```
 
+### Actionability
+
+Test Mule performs actionability checks when interacting with the page using the [User API](#user-api-testmuleuser). This concept is closely modeled after [Cypress](https://docs.cypress.io/guides/core-concepts/interacting-with-elements.html#Actionability) and [Playwright's](https://playwright.dev/docs/actionability) implementations of actionability.
+
+The core concept behind actionability is that if a real user would not be able to perform an action in your page, you should not be able to perform the actions in your test either. For example, since a user cannot click on an invisible element, your test should not allow you to click on invisible elements.
+
+We are working on adding more actionability checks.
+
+Here are the actionability checks that are currently implemented. Different methods in the User API perform different actionability checks based on what makes sense. In the API documentation for the [User API](#user-api-testmuleuser), the actionability checks that each method performs are listed.
+
+#### Attached
+
+Ensures that the element is attached to the DOM, using [`Node.isConnected`](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected). For example, if you use `document.createElement()`, the created element is not attached to the DOM until you use `ParentNode.append()` or similar.
+
+#### Visible
+
+Ensures that the element is visible to a user. Currently, the following checks are performed (more will likely be added):
+
+- Element is [Attached](#attached) to the DOM
+- Element does not have `display: none` or `visibility: hidden`
+- Element has a size (its [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) has a non-zero width and height)
+- Element's opacity is greater than 0.05 (opacity of parent elements are considered)
+
 ## Full Example
 
 There is a menu example in the [examples folder](./examples/menu/index.test.ts)
@@ -399,22 +423,64 @@ The user API allows you to perform actions on behalf of the user. If you have us
 
 > **Warning**: The User API is in progress. It should be safe to use the existing methods, but keep in mind that more methods will be added in the future, and more checks will be performed for existing methods as well.
 
-#### `TestMuleUser.click(element: ElementHandle): Promise<void>`
+#### `TestMuleUser.click(element: ElementHandle, options?: { force?: boolean }): Promise<void>`
+
+Clicks an element, if the element is visible and the center of it is not covered by another element. If the center of the element is covered by another element, an error is thrown. This is a thin wrapper around Puppeteer's [`ElementHandle.click` method](https://pptr.dev/#?product=Puppeteer&version=v7.0.1&show=api-elementhandleclickoptions). The difference is that `TestMuleUser.click` checks that the target element is an element that actually can be clicked before clicking it!
 
-Clicks an element, if the element is visible and the center of it is not covered by another element. If the center of the element is covered by another element, an error is thrown. This is a thin wrapper around Puppeteer's [`ElementHandle.click` method](https://pptr.dev/#?product=Puppeteer&version=v7.0.1&show=api-elementhandleclickoptions). The difference is that `TestMuleUser.click` checks that the target element is not covered before performing the click. Don't forget to `await`, since this returns a Promise!
+**Actionability checks**: It refuses to click elements that are not [**attached**](#attached) or not [**visible**](#visible). You can override the visibility check by passing `{ force: true }`.
+
+Additionally, it refuses to click an element if there is another element covering it. `{ force: true }` overrides this behavior.
 
 ```js
 import { withBrowser } from 'test-mule';
 
 test(
   'click example',
-  withBrowser(async ({ user, screen }) => {
+  withBrowser(async ({ utils, user, screen }) => {
+    await utils.injectHTML('<button>button text</button>');
     const button = await screen.getByRole('button', { name: /button text/i });
     await user.click(button);
   }),
 );
 ```
 
+#### `TestMuleUser.type(element: ElementHandle, text: string, options?: { force?: boolean }): Promise<void>`
+
+Types text into an element, if the element is visible. The element must be an `<input>` or `<textarea>` or have `[contenteditable]`.
+
+If the element already has text in it, the additional text is appended to the existing text. **This is different from Puppeteer and Playwright's default .type behavior**.
+
+**Actionability checks**: It refuses to type into elements that are not [**attached**](#attached) or not [**visible**](#visible). You can override the visibility check by passing `{ force: true }`.
+
+In the text, you can pass special commands using curly brackets to trigger special keypresses, similar to [user-event](https://github.com/testing-library/user-event#special-characters) and [Cypress](https://docs.cypress.io/api/commands/type.html#Arguments). Open an issue if you want more commands available here! Note: If you want to simulate individual keypresses independent from a text field, you can use Puppeteer's [page.keyboard API](https://pptr.dev/#?product=Puppeteer&version=v7.1.0&show=api-pagekeyboard)
+
+| Text string    | Key        | Notes                                                                                   |
+| -------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `{enter}`      | Enter      |                                                                                         |
+| `{tab}`        | Tab        |                                                                                         |
+| `{backspace}`  | Backspace  |                                                                                         |
+| `{del}`        | Delete     |                                                                                         |
+| `{selectall}`  | N/A        | Selects all the text of the element. Does not work for elements using `contenteditable` |
+| `{arrowleft}`  | ArrowLeft  |                                                                                         |
+| `{arrowright}` | ArrowRight |                                                                                         |
+| `{arrowup}`    | ArrowUp    |                                                                                         |
+| `{arrowdown}`  | ArrowDown  |                                                                                         |
+
+```js
+import { withBrowser } from 'test-mule';
+
+test(
+  'type example',
+  withBrowser(async ({ utils, user, screen }) => {
+    await utils.injectHTML('<input />');
+    const button = await user.type(
+      button,
+      'this is some text..{backspace}{arrowleft} asdf',
+    );
+  }),
+);
+```
+
 ### Utilities API: `TestMuleUtils`
 
 The utilities API provides shortcuts for loading and running code in the browser. The methods are wrappers around behavior that can be performed more verbosely with the [Puppeteer `Page` object](#testmulecontextpage). This API is exposed via the [`utils` property in `TestMuleContext`](#testmulecontextutils-testmuleutils)
diff --git a/jest.config.js b/jest.config.js
index 2832f851..707e7bd5 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -4,6 +4,7 @@ module.exports = {
     'test-mule': '<rootDir>/dist/cjs/index.cjs',
   },
   testRunner: 'jest-circus/runner',
+  watchPathIgnorePatterns: ['<rootDir>/src/'],
   transform: {
     '^.+\\.tsx?$': ['esbuild-jest', { sourcemap: true }],
   },
diff --git a/rollup.config.js b/rollup.config.js
index 3b2b9aaf..944369c8 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -1,5 +1,6 @@
 import jestDomConfig from './src/jest-dom/rollup.config';
 import pptrTestingLibraryConfig from './src/pptr-testing-library-client/rollup.config';
+import userUtilsConfig from './src/user-util/rollup.config';
 
 import dts from 'rollup-plugin-dts';
 import babel from '@rollup/plugin-babel';
@@ -40,6 +41,7 @@ const typesConfig = {
 
 export default [
   mainConfig,
+  userUtilsConfig,
   jestDomConfig,
   pptrTestingLibraryConfig,
   typesConfig,
diff --git a/src/index.ts b/src/index.ts
index 47320261..f4ec4653 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -404,11 +404,18 @@ const createTab = async ({
   const within: TestMuleContext['within'] = (
     element: puppeteer.ElementHandle | null,
   ) => {
-    assertElementHandle(element, within, 'within(el)', 'el');
+    assertElementHandle(element, within);
     return getQueriesForElement(page, state, element);
   };
 
-  return { screen, utils, page, within, user: testMuleUser(state), state };
+  return {
+    screen,
+    utils,
+    page,
+    within,
+    user: testMuleUser(page, state),
+    state,
+  };
 };
 
 afterAll(async () => {
@@ -419,3 +426,4 @@ afterAll(async () => {
 });
 
 export const devices = puppeteer.devices;
+export { port };
diff --git a/src/user-util/index.ts b/src/user-util/index.ts
new file mode 100644
index 00000000..c53c859c
--- /dev/null
+++ b/src/user-util/index.ts
@@ -0,0 +1,65 @@
+export { printElement } from '../serialize';
+
+export const assertAttached = (el: Element) => {
+  if (!el.isConnected) {
+    throw error`Cannot perform action on element that is not attached to the DOM:
+${el}`;
+  }
+};
+
+// Element is visible if all:
+// - it is attached to the DOM
+// - it has a rendered size (its rendered width and height are not zero)
+// - Computed opacity (product of opacity of ancestors) is non-zero
+// - is not display: none or visibility: hidden
+export const assertVisible = (el: Element) => {
+  assertAttached(el);
+
+  // getComputedStyle allows inherited properties to be seen correctly
+  const style = getComputedStyle(el);
+
+  if (style.visibility === 'hidden') {
+    throw error`Cannot perform action on element that is not visible (it has visibility:hidden):
+${el}`;
+  }
+
+  // The opacity of a parent element affects the rendering of a child element,
+  // but the opacity property is not inherited, so this computes the rendered opacity
+  // by walking up the tree and multiplying the opacities.
+  let opacity = Number(style.opacity);
+  let opacityEl: Element | null = el;
+  while (opacity && (opacityEl = opacityEl.parentElement)) {
+    opacity *= (getComputedStyle(opacityEl).opacity as any) as number;
+  }
+
+  if (opacity < 0.05) {
+    throw error`Cannot perform action on element that is not visible (it is near zero opacity):
+${el}`;
+  }
+
+  const rect = el.getBoundingClientRect();
+  // handles: rendered width is zero or rendered height is zero or display:none
+  if (rect.width * rect.height === 0) {
+    throw error`Cannot perform action on element that is not visible (it was not rendered or has a size of zero):
+${el}`;
+  }
+};
+
+// this is used to generate the arrays that are used
+// to produce messages with live elements in the browser,
+// and stringified elements in node
+// example usage:
+// error`something bad happened: ${el}`
+// returns { error: ['something bad happened', el]}
+export const error = (
+  literals: TemplateStringsArray,
+  ...placeholders: Element[]
+) => {
+  return {
+    error: literals.reduce((acc, val, i) => {
+      if (i !== 0) acc.push(placeholders[i - 1]);
+      if (val !== '') acc.push(val);
+      return acc;
+    }, [] as (string | Element)[]),
+  };
+};
diff --git a/src/user-util/rollup.config.js b/src/user-util/rollup.config.js
new file mode 100644
index 00000000..6e05b34a
--- /dev/null
+++ b/src/user-util/rollup.config.js
@@ -0,0 +1,18 @@
+import babel from '@rollup/plugin-babel';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import { terser } from 'rollup-plugin-terser';
+
+const extensions = ['.js', '.jsx', '.es6', '.es', '.mjs', '.ts', '.tsx'];
+
+/** @type {import('rollup').RollupOptions} */
+const config = {
+  input: ['src/user-util/index.ts'],
+  plugins: [
+    babel({ babelHelpers: 'bundled', extensions }),
+    nodeResolve({ extensions }),
+    terser({ ecma: 2019 }),
+  ],
+  output: { file: 'dist/user-util.js' },
+};
+
+export default config;
diff --git a/src/user.ts b/src/user.ts
index 6f5ae90f..50e4d218 100644
--- a/src/user.ts
+++ b/src/user.ts
@@ -1,76 +1,258 @@
-import type { ElementHandle } from 'puppeteer';
+import type { ElementHandle, JSHandle, Page } from 'puppeteer';
 import {
   assertElementHandle,
   jsHandleToArray,
   removeFuncFromStackTrace,
 } from './utils';
+import { port } from './vite-server';
 
 export interface TestMuleUser {
   /** Clicks an element, if the element is visible and not covered by another element */
-  click(element: ElementHandle | null): Promise<void>;
+  click(
+    element: ElementHandle | null,
+    options?: { force?: boolean },
+  ): Promise<void>;
+  type(
+    element: ElementHandle | null,
+    text: string,
+    options?: { delay?: number; force?: boolean },
+  ): Promise<void>;
 }
 
-export const testMuleUser = (state: { isTestFinished: boolean }) => {
+const forgotAwaitMsg =
+  'Cannot interact with browser after test finishes. Did you forget to await?';
+
+export const testMuleUser = (
+  page: Page,
+  state: { isTestFinished: boolean },
+) => {
   const user: TestMuleUser = {
-    async click(el) {
-      assertElementHandle(el, user.click, 'user.click(el)', 'el');
+    async click(el, { force = false } = {}) {
+      assertElementHandle(el, user.click);
 
       const forgotAwaitError = removeFuncFromStackTrace(
-        new Error(
-          `Cannot interact with browser using user.click after test finishes. Did you forget to await?`,
-        ),
+        new Error(forgotAwaitMsg),
         user.click,
       );
 
-      const failed = await el
-        .evaluateHandle((clickEl) => {
-          const clickElRect = clickEl.getBoundingClientRect();
+      const handleForgotAwait = (error: Error) => {
+        throw state.isTestFinished && /target closed/i.test(error.message)
+          ? forgotAwaitError
+          : error;
+      };
+
+      await el
+        .evaluateHandle(
+          runWithUtils((utils, clickEl, force: boolean) => {
+            try {
+              utils.assertAttached(clickEl);
+              if (!force) utils.assertVisible(clickEl);
+            } catch (e) {
+              return e;
+            }
+            if (!force) {
+              const clickElRect = clickEl.getBoundingClientRect();
+
+              // See if there is an element covering the center of the click target element
+              const coveringEl = document.elementFromPoint(
+                Math.floor(clickElRect.x + clickElRect.width / 2),
+                Math.floor(clickElRect.y + clickElRect.height / 2),
+              )!;
+              if (coveringEl === clickEl || clickEl.contains(coveringEl))
+                return;
+              // TODO: try to find other points on the element that are clickable,
+              // in case the covering element does not cover the whole click-target element
+              return utils.error`Could not click element:
+${clickEl}
+
+Element was covered by:
+${coveringEl}`;
+            }
+          }),
+          force,
+        )
+        .then(throwBrowserError(user.click))
+        .catch(handleForgotAwait);
+
+      await el.click().catch(handleForgotAwait);
+    },
+
+    // Implementation notes:
+    // - *Appends* to existing text - different from some other tools:
+    //   Puppeteer and Playwright *Prepend*
+    //   Cypress and user-event *Append*
+    // - The names of the commands in curly brackets are mirroring the user-event command names
+    //   *NOT* the Cypress names.
+    //   i.e. Cypress uses {leftarrow} but user-event and test-mule use {arrowleft}
+    async type(el, text, { delay = 10, force = false } = {}) {
+      assertElementHandle(el, user.type);
+
+      const forgotAwaitError = removeFuncFromStackTrace(
+        new Error(forgotAwaitMsg),
+        user.type,
+      );
+      const handleForgotAwait = (error: Error) => {
+        throw state.isTestFinished && /target closed/i.test(error.message)
+          ? forgotAwaitError
+          : error;
+      };
 
-          // See if there is an element covering the center of the click target element
-          const coveringEl = document.elementFromPoint(
-            Math.floor(clickElRect.x + clickElRect.width / 2),
-            Math.floor(clickElRect.y + clickElRect.height / 2),
+      // Splits input into chunks
+      // i.e. "something{backspace}something{enter} "
+      // => ["something", "{backspace}", "something", "{enter}"]
+      const chunks: string[] = [];
+      while (text) {
+        if (text.startsWith('{')) {
+          text = text.replace(
+            /^{[^{}]*}/,
+            (substr) => (chunks.push(substr.toLowerCase()), ''),
           );
-          if (coveringEl === clickEl || clickEl.contains(coveringEl)) return;
-          // TODO: try to find other points on the element that are clickable,
-          // in case the covering element does not cover the whole click-target element
-          const messagePart1 =
-            'user.click(element)\n\nCould not click element:\n';
-          const messagePart2 = '\n\nElement was covered by:\n';
-          // TODO: instead of using .outerHTML use the html formatter
-          return {
-            message:
-              messagePart1 +
-              clickEl.outerHTML +
-              messagePart2 +
-              coveringEl!.outerHTML,
-            messageForBrowser: [
-              messagePart1,
-              clickEl,
-              messagePart2,
-              coveringEl,
-            ],
-          };
-        })
-        .catch((error) => {
-          if (state.isTestFinished && /target closed/i.test(error.message)) {
-            throw forgotAwaitError;
-          }
-          throw error;
-        });
-
-      const { message } = (await failed.jsonValue()) || ({} as any);
-
-      if (message) {
-        const error = new Error(message) as any;
-        error.messageForBrowser = await jsHandleToArray(
-          await failed.getProperty('messageForBrowser'),
-        );
-        throw removeFuncFromStackTrace(error, user.click);
+        } else {
+          text = text.replace(/^[^{]*/, (substr) => (chunks.push(substr), ''));
+        }
       }
+      await el
+        .evaluateHandle(
+          runWithUtils((utils, el, force: boolean) => {
+            try {
+              utils.assertAttached(el);
+              if (!force) utils.assertVisible(el);
+            } catch (e) {
+              return e;
+            }
+
+            if (document.activeElement === el) {
+              // No need to focus it, it is already focused
+              // We won't move the cursor to the end either because that could be unexpected
+            } else if (
+              el instanceof HTMLInputElement ||
+              el instanceof HTMLTextAreaElement
+            ) {
+              el.focus();
+              // Move cursor to the end
+              const end = el.value.length;
+              el.setSelectionRange(end, end);
+            } else if (el instanceof HTMLElement && el.isContentEditable) {
+              el.focus();
+              const range = el.ownerDocument.createRange();
+              range.selectNodeContents(el);
+              const end = el.textContent!.length;
+              range.setStart(el.firstChild!, end);
+              range.setEnd(el.firstChild!, end);
+              // Move cursor to the end
+              const sel = el.ownerDocument.getSelection()!;
+              sel.removeAllRanges();
+              sel.addRange(range);
+            } else {
+              return utils.error`Cannot type in element that is not typeable:
+${el}
+Element must be an <input> or <textarea> or an element with the contenteditable attribute.`;
+            }
+          }),
+          force,
+        )
+        .then(throwBrowserError(user.type))
+        .catch(handleForgotAwait);
 
-      await el.click();
+      for (const chunk of chunks) {
+        const key = typeCommandsMap[chunk];
+        if (key) {
+          await page.keyboard.press(key, { delay }).catch(handleForgotAwait);
+        } else if (chunk === '{selectall}') {
+          await el
+            .evaluateHandle(
+              runWithUtils((utils, el) => {
+                if (
+                  el instanceof HTMLInputElement ||
+                  el instanceof HTMLTextAreaElement
+                ) {
+                  el.select();
+                } else {
+                  return utils.error`{selectall} command is only available for <input> and textarea elements, received: ${el}`;
+                }
+              }),
+            )
+            .then(throwBrowserError(user.type))
+            .catch(handleForgotAwait);
+        } else {
+          await page.keyboard.type(chunk, { delay }).catch(handleForgotAwait);
+        }
+      }
     },
   };
   return user;
 };
+
+// note: command chunks are already lowercased so it is not case-sensitive
+// left side: command
+// right side: passed to pptr keyboard.press, full list at https://github.com/puppeteer/puppeteer/blob/main/src/common/USKeyboardLayout.ts
+const typeCommandsMap: Record<string, string> = {
+  '{enter}': 'Enter',
+  '{arrowleft}': 'ArrowLeft',
+  '{arrowright}': 'ArrowRight',
+  '{arrowup}': 'ArrowLeft',
+  '{arrowdown}': 'ArrowDown',
+  '{tab}': 'Tab',
+  '{backspace}': 'Backspace',
+  '{del}': 'Delete',
+};
+
+const runWithUtils = <Args extends any[], Return extends unknown>(
+  fn: (userUtil: typeof import('./user-util'), ...args: Args) => Return,
+): ((...args: Args) => Promise<Return>) => {
+  return new Function(
+    '...args',
+    `return import("http://localhost:${port}/@test-mule/user-util")
+    .then((utils) => [utils, (0, ${fn.toString()})(utils, ...args)])
+    .then(([utils, result]) => {
+      if (result && typeof result === 'object' && result.error) {
+        const msgWithLiveEls = result.error
+        if (typeof msgWithLiveEls === 'string') return { error: msgWithLiveEls }
+        const msgWithStringEls = msgWithLiveEls
+          .map(el => {
+            if (el instanceof Element || el instanceof Document)
+              return utils.printElement(el)
+            return el
+          })
+          .join('')
+        return { error: { msgWithLiveEls, msgWithStringEls } }
+      }
+      return result
+    })`,
+  ) as any;
+};
+
+/**
+ * When code that is evaluated in the browser returns {error: ...}, this function causes an error to be thrown in Node.
+ * This is better than just throwing directly from the browser code because that would cause the error to be wrapped by Puppeteer's EvaluationError, which causes a confusing stack trace.
+ */
+const throwBrowserError = (func: (...params: any) => any) => async (
+  result: JSHandle,
+) => {
+  const resultJSON = (await result.jsonValue()) as any;
+  if (resultJSON?.error) {
+    let err;
+    if (typeof resultJSON.error === 'string') {
+      err = new Error(resultJSON.error);
+    } else {
+      const errorProp = await result.getProperty('error');
+      const errorProperties = Object.fromEntries(
+        await errorProp.getProperties(),
+      );
+      if (errorProperties.msgWithStringEls && errorProperties.msgWithLiveEls) {
+        err = new Error(
+          (await errorProperties.msgWithStringEls.jsonValue()) as any,
+        );
+        // @ts-expect-error
+        err.messageForBrowser = await jsHandleToArray(
+          errorProperties.msgWithLiveEls,
+        );
+      } else {
+        err = new Error((await errorProp.jsonValue()) as any);
+      }
+    }
+    removeFuncFromStackTrace(err, func);
+    throw err;
+  }
+  return result;
+};
diff --git a/src/utils.ts b/src/utils.ts
index 3f7b2170..ec62d100 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -17,9 +17,7 @@ export const jsHandleToArray = async (arrayHandle: JSHandle) => {
 export const assertElementHandle: (
   input: unknown,
   fn: (...params: any[]) => any,
-  signature: string,
-  varName: string,
-) => asserts input is ElementHandle = (input, fn, signature, varName) => {
+) => asserts input is ElementHandle = (input, fn) => {
   const type =
     input === null
       ? 'null'
@@ -27,9 +25,7 @@ export const assertElementHandle: (
       ? 'Promise'
       : typeof input;
 
-  const messageStart = `${signature}
-
-${varName} must be an ElementHandle\n\n`;
+  const messageStart = `element must be an ElementHandle\n\n`;
   if (type === 'Promise') {
     throw removeFuncFromStackTrace(
       new Error(messageStart + 'Received Promise. Did you forget await?'),
@@ -61,7 +57,7 @@ ${varName} must be an ElementHandle\n\n`;
  */
 export const removeFuncFromStackTrace = (
   error: Error,
-  fn: (...params: any[]) => any,
+  fn: (...params: any) => any,
 ) => {
   Error.captureStackTrace?.(error, fn);
   return error;
diff --git a/src/vite-server.ts b/src/vite-server.ts
index d0b68f1a..794f8310 100644
--- a/src/vite-server.ts
+++ b/src/vite-server.ts
@@ -71,6 +71,8 @@ export const createServer = async () => {
         currentDir,
         id === '/@test-mule/jest-dom'
           ? '../jest-dom.js'
+          : id === '/@test-mule/user-util'
+          ? '../user-util.js'
           : '../pptr-testing-library-client.js',
       );
     },
diff --git a/tests/forgot-await.test.ts b/tests/forgot-await.test.ts
index 2bbb6d4f..9a36d440 100644
--- a/tests/forgot-await.test.ts
+++ b/tests/forgot-await.test.ts
@@ -83,7 +83,7 @@ test('forgot await in user.click', (done) => {
     const button = await screen.getByText('Hi');
     user.click(button).catch(async (error) => {
       expect(await printErrorFrames(error)).toMatchInlineSnapshot(`
-        "Error: Cannot interact with browser using user.click after test finishes. Did you forget to await?
+        "Error: Cannot interact with browser after test finishes. Did you forget to await?
         -------------------------------------------------------
         tests/forgot-await.test.ts
 
@@ -96,3 +96,23 @@ test('forgot await in user.click', (done) => {
     });
   })();
 });
+
+test('forgot await in user.type', (done) => {
+  withBrowser(async ({ user, utils, screen }) => {
+    await utils.injectHTML('<input />');
+    const input = await screen.getByRole('textbox');
+    user.type(input, 'hello').catch(async (error) => {
+      expect(await printErrorFrames(error)).toMatchInlineSnapshot(`
+        "Error: Cannot interact with browser after test finishes. Did you forget to await?
+        -------------------------------------------------------
+        tests/forgot-await.test.ts
+
+            user.type(input, 'hello').catch(async (error) => {
+                 ^
+        -------------------------------------------------------
+        dist/cjs/index.cjs"
+      `);
+      done();
+    });
+  })();
+});
diff --git a/tests/user/actionability.test.ts b/tests/user/actionability.test.ts
new file mode 100644
index 00000000..9c4efcde
--- /dev/null
+++ b/tests/user/actionability.test.ts
@@ -0,0 +1,156 @@
+import type { ElementHandle } from 'puppeteer';
+import { port, withBrowser } from 'test-mule';
+
+const runWithUtils = <Args extends any[], Return extends unknown>(
+  fn: (userUtil: typeof import('../../src/user-util'), ...args: Args) => Return,
+): ((...args: Args) => Promise<Return>) => {
+  return new Function(
+    '...args',
+    `return import("http://localhost:${port}/@test-mule/user-util")
+    .then((utils) => [utils, (0, ${fn.toString()})(utils, ...args)])
+    .then(([utils, result]) => {
+      if (result && typeof result === 'object' && result.error) {
+        const msgWithLiveEls = result.error
+        if (typeof msgWithLiveEls === 'string') return { error: msgWithLiveEls }
+        const msgWithStringEls = msgWithLiveEls
+          .map(el => {
+            if (el instanceof Element || el instanceof Document)
+              return utils.printElement(el)
+            return el
+          })
+          .join('')
+        return { error: { msgWithLiveEls, msgWithStringEls } }
+      }
+      return result
+    })`,
+  ) as any;
+};
+
+const isAttached = (el: ElementHandle) =>
+  el.evaluate(
+    runWithUtils((utils, clickEl) => {
+      try {
+        utils.assertAttached(clickEl);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    }),
+  );
+
+const isVisible = (el: ElementHandle) =>
+  el.evaluate(
+    runWithUtils((utils, clickEl) => {
+      try {
+        utils.assertVisible(clickEl);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    }),
+  );
+
+describe('attached', () => {
+  test(
+    'isAttached returns true until element is removed',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<button>Hi</button>');
+      const div = await screen.getByRole('button');
+      expect(await isAttached(div)).toBe(true);
+      await div.evaluate((el) => el.remove());
+      expect(await isAttached(div)).toBe(false);
+    }),
+  );
+});
+
+describe('visible', () => {
+  test(
+    'visible element returns true for isVisible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<button>Hi</button>');
+      const button = await screen.getByRole('button');
+      expect(await isVisible(button)).toBe(true);
+    }),
+  );
+  test(
+    'non-attached element is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<button>Hi</button>');
+      const button = await screen.getByRole('button');
+      await button.evaluate((el) => el.remove());
+      expect(await isVisible(button)).toBe(false);
+    }),
+  );
+  test(
+    'opacity:0 is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<button style="opacity:0">Hi</button>');
+      const button = await screen.getByRole('button');
+      expect(await isVisible(button)).toBe(false);
+    }),
+  );
+  test(
+    'width:0 is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="width:0">Hi</div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'height:0 is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="height:0">Hi</div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'display:none is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="display:none">Hi</div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'visibility:hidden is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="visibility:hidden">Hi</div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'hidden attribute is not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div hidden>Hi</div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'hiding parent makes child not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div hidden><div>Hi</div></div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'zero-size parent makes child not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="width:0"><div>Hi</div></div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+  test(
+    'opacity:0 on parent makes child not visible',
+    withBrowser(async ({ utils, screen }) => {
+      await utils.injectHTML('<div style="opacity:0"><div>Hi</div></div>');
+      const div = await screen.getByText('Hi');
+      expect(await isVisible(div)).toBe(false);
+    }),
+  );
+});
diff --git a/tests/user/click.test.ts b/tests/user/click.test.ts
index 0e9aea63..faefc867 100644
--- a/tests/user/click.test.ts
+++ b/tests/user/click.test.ts
@@ -51,7 +51,7 @@ const setupOverlappingElements = async (
 };
 
 test(
-  "puppeteer's .click clicks the covering element",
+  "puppeteer's .click clicks an overlapping element",
   withBrowser(async ({ utils, page }) => {
     const [first, second] = await setupOverlappingElements(utils, page);
 
@@ -66,14 +66,11 @@ test(
 );
 
 test(
-  'user.click throws an error that the element is being covered',
+  'throws an error that the element is being covered',
   withBrowser(async ({ utils, page, user }) => {
     const [first, second] = await setupOverlappingElements(utils, page);
-
     await expect(user.click(first)).rejects.toThrowErrorMatchingInlineSnapshot(`
-            "user.click(element)
-
-            Could not click element:
+            "Could not click element:
             <div id=\\"first\\">First Box</div>
 
             Element was covered by:
@@ -87,7 +84,20 @@ test(
 );
 
 test(
-  'user.click works fine for non-covered elements',
+  '{ force: true } overrides covering check',
+  withBrowser(async ({ utils, page, user }) => {
+    const [first, second] = await setupOverlappingElements(utils, page);
+    await user.click(first, { force: true });
+
+    // With { force: true } it triggers the click, even though the element is covered,
+    // so the covered element gets clicked (Puppeteer's default behavior)
+    await expect(first).toBeInTheDocument();
+    await expect(second).not.toBeInTheDocument();
+  }),
+);
+
+test(
+  'works fine for non-covered elements',
   withBrowser(async ({ utils, page, user }) => {
     const [first, second] = await setupOverlappingElements(utils, page, false);
 
@@ -98,7 +108,7 @@ test(
 );
 
 test(
-  'user.click works fine for child elements that "cover" the parent',
+  'works fine for child elements that "cover" the parent',
   withBrowser(async ({ utils, user, screen }) => {
     // The text in the button "covers" the button,
     // but the button should still be clickable
@@ -115,3 +125,46 @@ test(
     await user.click(button);
   }),
 );
+
+describe('actionability checks', () => {
+  test(
+    'refuses to click detached element',
+    withBrowser(async ({ utils, user, screen }) => {
+      await utils.injectHTML(`<button>hi</button>`);
+      const button = await screen.getByRole('button', { name: /hi/i });
+      // Remove element from the DOM but still keep a reference to it
+      await button.evaluate((b) => b.remove());
+      await expect(user.click(button)).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not attached to the DOM:
+              <button>hi</button>"
+            `);
+      // Puppeteer's .click doesn't work on detached elements,
+      // so even with { force: true } we will not attempt to click
+      await expect(user.click(button, { force: true })).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not attached to the DOM:
+              <button>hi</button>"
+            `);
+    }),
+  );
+
+  test(
+    'refuses to click non-visible element',
+    withBrowser(async ({ utils, user, screen }) => {
+      await utils.injectHTML(`
+      <button style="opacity: 0">hi</button>
+    `);
+
+      const button = await screen.getByRole('button', { name: /hi/i });
+
+      await expect(user.click(button)).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not visible (it is near zero opacity):
+              <button style=\\"opacity: 0\\">hi</button>"
+            `);
+      // with { force: true } it should skip the visibility check
+      await user.click(button, { force: true });
+    }),
+  );
+});
diff --git a/tests/user/type.test.ts b/tests/user/type.test.ts
new file mode 100644
index 00000000..21e1f181
--- /dev/null
+++ b/tests/user/type.test.ts
@@ -0,0 +1,216 @@
+import type { ElementHandle } from 'puppeteer';
+import { withBrowser } from 'test-mule';
+
+type InputHandle = ElementHandle<HTMLInputElement>;
+type FormHandle = ElementHandle<HTMLFormElement>;
+
+test(
+  'element text changes, and separate input events are fired',
+  withBrowser(async ({ user, utils, screen }) => {
+    await utils.injectHTML(
+      `<input oninput="document.querySelector('h1').innerHTML++"/>
+      <h1>0</h1>`,
+    );
+    const input: InputHandle = await screen.getByRole('textbox');
+    await user.type(input, 'hiiiiiiii');
+    const heading = await screen.getByRole('heading');
+    // 9 input events should have fired
+    expect(await heading.evaluate((h) => Number(h.innerHTML))).toEqual(9);
+    await expect(input).toHaveValue('hiiiiiiii');
+  }),
+);
+
+test(
+  'appends to existing text (<input />)',
+  withBrowser(async ({ user, utils, screen }) => {
+    await utils.injectHTML(`<input value="1234" />`);
+    const input: InputHandle = await screen.getByRole('textbox');
+    await user.type(input, '5678');
+    await expect(input).toHaveValue('12345678');
+  }),
+);
+
+test(
+  'appends to existing text (<textarea />)',
+  withBrowser(async ({ user, utils, screen }) => {
+    await utils.injectHTML(`<textarea>1234</textarea>`);
+    const textarea: InputHandle = await screen.getByRole('textbox');
+    await user.type(textarea, '5678');
+    await expect(textarea).toHaveValue('12345678');
+  }),
+);
+
+test(
+  'appends to existing text (<div contenteditable />)',
+  withBrowser(async ({ user, utils, screen }) => {
+    // directly on the contenteditable element
+    await utils.injectHTML(`<div contenteditable role="textbox">1234</div>`);
+    const div: InputHandle = await screen.getByRole('textbox');
+    await user.type(div, '5678');
+    expect(await div.evaluate((div) => div.textContent)).toEqual('12345678');
+
+    // ancestor element is contenteditable
+    await utils.injectHTML(`<div contenteditable><a href="hi">1234</a></div>`);
+    const link = await screen.getByText('1234');
+    await user.type(link, '5678');
+    expect(
+      await link.evaluate((link) => link.parentElement!.textContent),
+    ).toEqual('12345678');
+  }),
+);
+
+describe('special character sequences', () => {
+  test(
+    '{enter} in <input> submits form',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(
+        `<form name="searchForm" onsubmit="event.preventDefault(); this.remove()"><input value="1234" /></form>`,
+      );
+      const input: InputHandle = await screen.getByRole('textbox');
+      const form: FormHandle = await screen.getByRole('form');
+      await expect(form).toBeInTheDocument();
+      // it shouldn't care about the capitalization in the command sequences
+      await user.type(input, 'hello{eNtEr}');
+      await expect(input).toHaveValue('1234hello');
+      await expect(form).not.toBeInTheDocument();
+    }),
+  );
+  test(
+    '{enter} in <textarea> adds newline',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<textarea>1234</textarea>`);
+      const input: InputHandle = await screen.getByRole('textbox');
+      // it shouldn't care about the capitalization in the command sequences
+      await user.type(input, 'hello{ENteR}hello2');
+      await expect(input).toHaveValue('1234hello\nhello2');
+    }),
+  );
+  test(
+    'arrow keys',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<textarea>1234</textarea>`);
+      const input: InputHandle = await screen.getByRole('textbox');
+      await user.type(input, '56{arrowleft}insert');
+      await expect(input).toHaveValue('12345insert6');
+    }),
+  );
+  test(
+    '{tab} moves the focus to the next field and continues typing',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`
+        <label>
+          name
+          <input />
+        </label>
+        <label>
+          description
+          <textarea></textarea>
+        </label
+      `);
+      const nameBox: InputHandle = await screen.getByLabelText(/name/i);
+      const descriptionBox: InputHandle = await screen.getByLabelText(/desc/i);
+      await user.type(nameBox, '1234{tab}5678');
+      await expect(nameBox).toHaveValue('1234');
+      await expect(descriptionBox).toHaveValue('5678');
+    }),
+  );
+  test(
+    '{backspace} and {del}',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<textarea>1234</textarea>`);
+      const input: InputHandle = await screen.getByRole('textbox');
+      await user.type(input, '56{arrowleft}{backspace}');
+      await expect(input).toHaveValue('12346');
+      await user.type(input, '{arrowleft}{arrowleft}{del}');
+      await expect(input).toHaveValue('1246');
+    }),
+  );
+  test(
+    '{selectall}',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<textarea>1234</textarea>`);
+      const input: InputHandle = await screen.getByRole('textbox');
+      await user.type(input, '56{selectall}{backspace}abc');
+      await expect(input).toHaveValue('abc');
+    }),
+  );
+  test(
+    '{selectall} throws if used on contenteditable',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<div contenteditable>hello</div>`);
+      const div: ElementHandle<HTMLDivElement> = await screen.getByText(
+        'hello',
+      );
+      await expect(
+        user.type(div, '{selectall}'),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"{selectall} command is only available for <input> and textarea elements, received: <div contenteditable=\\"\\">hello</div>"`,
+      );
+    }),
+  );
+});
+
+test(
+  'delay',
+  withBrowser(async ({ user, utils, screen }) => {
+    await utils.injectHTML(`<textarea>1234</textarea>`);
+    const input: InputHandle = await screen.getByRole('textbox');
+    let startTime = new Date().getTime();
+    await user.type(input, '123');
+    expect(new Date().getTime() - startTime).toBeLessThan(100);
+    startTime = new Date().getTime();
+    await user.type(input, '123', { delay: 50 });
+    expect(new Date().getTime() - startTime).toBeGreaterThan(150);
+  }),
+);
+
+describe('actionability checks', () => {
+  test(
+    'refuses to type in element that is not in the DOM',
+    withBrowser(async ({ screen, user, utils }) => {
+      await utils.injectHTML('<input />');
+      const input = await screen.getByRole('textbox');
+      await input.evaluate((input) => input.remove());
+      await expect(user.type(input, 'hello')).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not attached to the DOM:
+              <input />"
+            `);
+      // Puppeteer's .type silently fails/refuses to type in an unattached element
+      // So our .type won't type in an unattached element even with { force: true }
+      await expect(user.type(input, 'hello', { force: true })).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not attached to the DOM:
+              <input />"
+            `);
+    }),
+  );
+  test(
+    'refuses to type in element that is not visible',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<input style="opacity: 0" />`);
+      const input: InputHandle = await screen.getByRole('textbox');
+      await expect(user.type(input, 'some text')).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot perform action on element that is not visible (it is near zero opacity):
+              <input style=\\"opacity: 0\\" />"
+            `);
+      // with { force: true } it should skip the visibility check
+      await user.type(input, 'some text', { force: true });
+      await expect(input).toHaveValue('some text');
+    }),
+  );
+  test(
+    'refuses to type in element that is not typeable',
+    withBrowser(async ({ user, utils, screen }) => {
+      await utils.injectHTML(`<div>Hi</div>`);
+      const div = await screen.getByText('Hi');
+      await expect(user.type(div, '5678')).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+              "Cannot type in element that is not typeable:
+              <div>Hi</div>
+              Element must be an <input> or <textarea> or an element with the contenteditable attribute."
+            `);
+    }),
+  );
+});