​
Prerequisites

Before installing Keystone, ensure you have the following:

​
Required Software

Node.js

Version 16.0 or higher required. Check your version with the node command.

Chrome/Chromium

Latest stable version required. Verify installation with the version command.

​
Chrome Installation

Keystone requires Chrome or Chromium to be installed on your system.
Install using Homebrew package manager or download directly from Google Chrome website.Image: macOS Chrome installation options would go here

​
Installation

Install Keystone CLI globally for easy access from any directory. After installation, verify the version to ensure proper setup. Image: Global installation command and verification would go here

​
Local Installation

For project-specific installations using npm, yarn, or pnpm. Add scripts to your package.json for convenient test execution. Image: Local installation options and package.json scripts would go here

​
Configuration

​
Environment Variables

Create a .env file in your project root with API credentials, runner configuration, and test settings. Image: Environment variables configuration example would go here

​
Configuration File

Create keystone.config.js for advanced configuration including browser settings, test parameters, API configuration, recording options, and file paths. Image: Configuration file structure example would go here

​
Verification

​
Chrome Detection

Run the Chrome detection script to verify proper installation and accessibility. The output shows Chrome location, version, and readiness status. Image: Chrome detection output example would go here

​
Test Connection

Start the runner and verify WebSocket connection by checking the health endpoint. A successful response confirms the runner is operational. Image: Connection test process and response would go here

​
Docker Setup

For containerized environments: 
FROM node:18-slim

# Install Chrome dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    ca-certificates \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libx11-6 \
    libxcomposite1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Install Chrome
RUN wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
    && apt-get update \
    && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

# Set Chrome path
ENV CHROME_PATH=/usr/bin/google-chrome

# Install Keystone
RUN npm install -g @keystone/cli

# Create app directory
WORKDIR /app

# Copy test files
COPY . .

# Expose WebSocket port
EXPOSE 9223

# Run tests
CMD ["keystone-runner", "start", "--headless"]
Build and run: 
docker build -t keystone-tests .
docker run -p 9223:9223 keystone-tests

​
Troubleshooting

​
Common Issues

​
Next Steps

Once installation is complete:
  1. Learn the CLI commands
  2. Set up your first test
  3. Configure CI/CD integration
  4. Explore step types