JavaScript keywords use the Keyword API: each keyword is an exported async function placed in the keywords/ directory of an npm project, executed on the Node.js agent. TypeScript keywords are executed exactly the same way once compiled, see TypeScript Keywords for the project setup.

If you are new to keyword development, read the Keyword Development page first.

Execution on the Node.js agent

Before a keyword is invoked, the Node.js agent prepares the npm project the keyword belongs to. Every module your keywords require has to be declared in the project’s package.json: the agent installs these dependencies itself, and no other modules are available to the keywords.

Workspace

The agent copies the project into a dedicated workspace (a folder under npm-project-workspaces in the agent’s working directory). Each agent token gets its own copy, so parallel executions never share an installation.

Workspaces are reused by later executions of the same project version on the same token, and deleted once they have been unused for a configurable idle time (one hour by default, see project workspace cleanup). As each workspace contains the installed node_modules, this setting has a direct impact on the disk space used by the agent.

Dependency installation

When a keyword is called for the first time in a session, the agent starts a dedicated Node.js process for this session and installs the project’s dependencies in the workspace. Subsequent keyword calls of the same session reuse this process and do not install again. The command depends on the content of the project:

• if the project contains a package-lock.json or npm-shrinkwrap.json, the agent runs npm ci --no-audit --no-fund, which installs exactly the dependency tree recorded in the lockfile. This makes executions reproducible: it is recommended to include the lockfile in your package
• otherwise, the agent runs npm install --no-audit --no-fund, which resolves the versions declared in package.json at execution time
• if the project contains no package.json, nothing is installed: the keywords can then only use their own files and the Node.js built-in modules

As the dependencies are installed on the agent, it needs access to an npm registry (the public one or the one configured in the npm configuration of the user running the agent) unless the project declares no dependency.

Installation failures

If the installation fails, the keyword call fails and the npm output is attached to the report as npm-install.log. In particular, npm ci fails if the lockfile is out of sync with package.json; the agent does not fall back to npm install in this case, so update the lockfile (by running npm install locally) before redeploying.

To get the npm output for successful installations too, set the debug property to true.

Local execution

When running keywords locally with the runner, the project is used in place and the runner always runs npm install --no-audit --no-fund, as npm ci would delete the node_modules folder the runner itself is loaded from.