Overview
The Plugin Loader module implements Taiko's plugin discovery, loading, and hook registration system, enabling third-party extensions to modify browser connection behavior and add subcommands.
Description
The Plugin Loader module provides the extension infrastructure for Taiko. It supports two mechanisms for plugin discovery: environment variable configuration and automatic detection from project dependencies.
Plugin discovery works as follows: if the TAIKO_PLUGIN environment variable is set, its comma-separated values are used as plugin names (automatically prefixed with taiko- if not already present). If the environment variable is not set, the module reads the current directory's package.json and collects all dependencies and devDependencies whose names start with taiko-.
The module also maintains a pluginHooks object that defines extension points for plugins. Currently, the only supported hook is preConnectionHook, which receives a target and options before a CDP connection is established and can modify them. Plugins register their hooks via the registerHooks function, which validates that only known hook names are used.
For CLI integration, getExecutablePlugins scans both global and local npm installation paths for installed taiko-* packages that declare a "capability": ["subcommands"] in their package.json. These plugins can extend Taiko's command-line interface with additional subcommands. Local plugins take precedence over global ones when both are present.
Usage
Use the Plugin Loader module to extend Taiko's functionality without modifying its core. Plugin authors create npm packages named taiko-* that export hooks or subcommands. End users activate plugins by adding them as project dependencies or setting the TAIKO_PLUGIN environment variable. The hook system is used internally during browser connection setup.
Code Reference
Source Location
Signature
function registerHooks(hooks) -> void
function getPlugins() -> Array<string>
function getExecutablePlugins() -> Object
const pluginHooks = { preConnectionHook: Function }
Import
const {
getPlugins,
getExecutablePlugins,
pluginHooks,
registerHooks,
} = require("./plugins");
I/O Contract
registerHooks(hooks)
| Parameter |
Type |
Description
|
hooks |
Object |
Object mapping hook names to handler functions. Currently only preConnectionHook is supported.
|
| Throws |
Condition
|
Error("Hook {name} not available in taiko to register") |
When a hook name is not recognized in pluginHooks.
|
getPlugins()
| Return |
Type |
Description
|
| plugins |
Array<string> |
Array of plugin package names (all prefixed with taiko-).
|
| Source |
Priority |
Description
|
TAIKO_PLUGIN env var |
1st (exclusive) |
Comma-separated list of plugin names. Names without taiko- prefix are auto-prefixed.
|
package.json |
2nd (fallback) |
All dependencies and devDependencies matching /^taiko-.*/.
|
getExecutablePlugins()
| Return |
Type |
Description
|
| plugins |
Object |
Object mapping short plugin names (without taiko- prefix) to their absolute filesystem paths. Local plugins override global plugins with the same name.
|
pluginHooks.preConnectionHook(target, options)
| Parameter |
Type |
Description
|
target |
string |
CDP target URL or identifier.
|
options |
Object |
Connection options.
|
| Return |
Type |
Description
|
| result |
{target, options} |
Potentially modified target and options. The default implementation passes them through unchanged.
|
Algorithm
Plugin Discovery
1. Check TAIKO_PLUGIN environment variable
a. If set: split by comma (with whitespace trimming)
b. For each name: if it doesn't start with "taiko-", prepend "taiko-"
c. Return the resulting array
2. If TAIKO_PLUGIN not set:
a. Check for ./package.json existence
b. If missing: return empty array
c. Parse package.json
d. Collect all keys from dependencies and devDependencies
e. Filter for names matching /^taiko-.*/
f. Return the filtered array
Executable Plugin Discovery
1. Get global npm root path via `npm root -g`
2. Get local npm root path via `npm root`
3. For each path:
a. Read directory listing
b. Filter for directories (including symlinks) matching /^taiko-.*/
c. For each plugin, read its package.json
d. Filter for plugins with capability including "subcommands"
e. Build map: shortName (without taiko- prefix) -> absolutePath
4. Merge global and local maps (local takes precedence)
5. Return merged map
Hook Registration
The registerHooks function iterates over the provided hooks object and replaces the corresponding entry in pluginHooks. It validates each hook name against the known hooks, throwing an error for unrecognized names. This prevents typos from silently failing.
Usage Examples
// Discover plugins from environment or package.json
const { getPlugins } = require("./plugins");
const plugins = getPlugins();
// With TAIKO_PLUGIN="screenshotter,taiko-diagnostics":
// => ["taiko-screenshotter", "taiko-diagnostics"]
// Register a pre-connection hook (from a plugin)
const { registerHooks } = require("./plugins");
registerHooks({
preConnectionHook: (target, options) => {
options.extraHeaders = { "X-Custom": "value" };
return { target, options };
},
});
// Find executable plugins for CLI extension
const { getExecutablePlugins } = require("./plugins");
const execPlugins = getExecutablePlugins();
// => { "android": "/usr/lib/node_modules/taiko-android", ... }
Related Pages
