KeyBee 🐝

KeyBee is a small utility library to simulate a sequence of key presses in the browser. Great for testing and debugging Lightning-based Apps that rely on key-press–based navigation.

Installation

KeyBee is published in two flavours so you can choose the one that fits your use case:

ES Module (ESM)

Use the ES module for modern build setups (Vite, Webpack, Rollup, etc.) if you want to include the KeyBee library directly in your App bundle.

First install KeyBee from NPM: npm install keybee

Next import and use $keybee in your codebase, like so:

import $keybee from 'keybee'

$keybee.run([{ key: 'ArrowDown', repeat: 3 }, { key: 'Enter' }])

Additionally, you can also use this ESM version directly in the browser with <script type="module">.

IIFE build (global)

There is also a self-contained bundle that works in a plain <script> tag without any bundler. It attaches $keybee to the window object:

<script src="keybee.iife.min.js"></script>
<script>
  $keybee([{ key: 'ArrowDown', repeat: 3 }, { key: 'Enter' }])
</script>

Bookmarklet

You can also leverage the IIFE build to quickly add the library to an existing and running browser tab via a bookmarklet.

Once added to your bookmarks, clicking the KeyBee bookmark will import the library and make $keybee available on the global window object. After that you can interact with it directly in the web console and simulate key presses in an existing App.

👉 Get the KeyBee Bookmarklet

Usage

KeyBee comes with two exposed methods: $keybee.run and $keybee.defaults.

$keybee.run

This is the main KeyBee method that will run a sequence of key presses. It accepts a sequence array as the first argument and an optional second argument with options.

sequence

The sequence array is an array of objects which define the steps in the sequence.

A step object looks like this:

{
  key: 'ArrowUp', // key to simulate (required)
  repeat: 4,      // number of times to repeat this key (optional, defaults to 1)
  wait: 1000,     // ms of wait time after key presses (optional, defaults to 800ms)
}

Combined, a basic KeyBee sequence to navigate will look something like this:

$keybee.run([
  // navigate through a rail 5 times
  { key: 'ArrowRight', repeat: 5 },
  // navigate back to the start
  { key: 'ArrowLeft', repeat: 5 },
  // navigate to the side menu
  { key: 'ArrowLeft' },
  // move down in the menu
  { key: 'ArrowDown' },
  // open the menu item by pressing Enter
  { key: 'Enter' },
  // navigate through a rail 5 times
  { key: 'ArrowRight', repeat: 5 },
])

options

KeyBee can be configured with a few options. These can be passed to the $keybee.run() method as the second argument.

The options object has the following format:

{
  keyPressDuration: 30, // duration in ms of the key press (time between keydown and keyup, defaults to 30)
  wait: 800,            // default time in ms to wait after a key press (can be overridden per sequence step, defaults to 800)
  loop: 1,              // how many times to loop over the sequence (defaults to 1)
}

$keybee.defaults

Instead of passing the options separately to each $keybee.run invocation, it's also possible to specify default options once using the $keybee.defaults method.

These defaults will then be used in every $keybee.run sequence:

$keybee.defaults({
  keyPressDuration: 30, // duration in ms of the key press (time between keydown and keyup, defaults to 30)
  wait: 800,            // default time in ms to wait after a key press (can be overridden per sequence step, defaults to 800)
  loop: 1,              // how many times to loop over the sequence (defaults to 1)
})