Installing on a local machine

This route suits you if you want to

• test websites that aren't public, such as a staging environment,
• contribute to the development of Webperf Core, or
• have full control over the test environment.

Prerequisites

Python 3.13 or later

That's the requirement in the project's own install guide, and the version every regression test runs on.

brew install python@3.13

sudo apt update
sudo apt install python3 python3-venv python3-pip

Node.js 24 or later

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

Browser

Install at least one of Google Chrome and Mozilla Firefox. Chrome is the default; switch with --setting tests.sitespeed.browser=firefox.

Installation

1. Get the code

# If you're going to contribute: fork on GitHub first, then clone your fork
git clone https://github.com/YOUR-USERNAME/webperf_core.git

# Otherwise the original is enough
git clone https://github.com/Webperf-se/webperf_core.git

cd webperf_core

2. Create a virtual environment

python -m venv venv

Activate it:

venv\Scripts\activate

.\venv\Scripts\Activate.ps1

source venv/bin/activate

3. Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt
npm install --omit=dev

4. Validate the installation

python default.py --dependency

This checks that the Python packages, Node packages and browsers are in place, and reports what's missing.

Run your first test

python default.py -u https://webperf.se -t 22 -r

Configuration

Temporary settings

--setting (short form -s) changes a setting for that run only:

python default.py -u https://example.com -t 15 -r \
  --setting tests.sitespeed.browser=firefox

List every setting with its current value:

python default.py --setting ?

Permanent settings

Create a settings.json in the project root containing only what you want to change:

{
  "general": {
    "language": "en",
    "review": {
      "show": true,
      "details": true
    }
  }
}

If you'd rather start from your current setup, write it out to a file:

python default.py --save-setting settings.json

More about settings.json

Troubleshooting

pip install --user -r requirements.txt

sudo apt install -y chromium-browser firefox

Next steps

• All tests
• Configuration
• Contributing