Quickstart

1. Create Performance Tests
2. Connect your Repository
3. Run the Tests in your CI
4. Introduce a Performance Regression

​

Create Performance Tests

1. Install the CodSpeed plugin for pytest:
   Copy

   Ask AI

   pip install pytest-codspeed
   

2. Write a performance test using the @pytest.mark.benchmark marker:
   tests/test_sum_squares.py

   Copy

   Ask AI

   import pytest
   
   def sum_squares(arr):
       """Sum the squares of the numbers in an array."""
       total = 0
       for x in arr:
           total += x * x
       return total
   
   # Your tests can also be benchmarks
   @pytest.mark.benchmark
   def test_sum_squares():
       assert sum_squares(range(1000)) == 332833500
   

3. Run your performance tests locally:
   Copy

   Ask AI

   $ pytest tests/ --codspeed
   ============================= test session starts ====================
   platform darwin -- Python 3.13.0, pytest-7.4.4, pluggy-1.5.0
   codspeed: 3.0.0 (enabled, mode: walltime, timer_resolution: 41.7ns)
   rootdir: /home/user/codspeed-test, configfile: pytest.ini
   plugins: codspeed-3.0.0
   collected 1 items
   
   tests/test_sum_squares.py .                                    [ 100%]
   
                            Benchmark Results
   ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
   ┃     Benchmark  ┃ Time (best) ┃ Rel. StdDev ┃ Run time ┃ Iters  ┃
   ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━╋━━━━━━━━┫
   ┃test_sum_squares┃     1,873ns ┃        4.8% ┃    3.00s ┃ 66,930 ┃
   ┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━┛
   =============================== 1 benchmarked ========================
   =============================== 1 passed in 4.12s ====================
   

   Great! We set up our first performance test. Now, let’s track the performance in the CI with CodSpeed!

​

Connect your Repository

1. Login on CodSpeed
2. Go to settings and install the CodSpeed GitHub App by clicking on the “Import” button.
   
3. Select the organization or the user and add the repositories you want to use with CodSpeed:
4. Back in CodSpeed settings, configure a repository by clicking on the “Setup” button:
   

​

Run the Tests in your CI

1. Create a new GitHub Actions workflow file to run your benchmarks:
   .github/workflows/codspeed.yml

   Copy

   Ask AI

   name: CodSpeed Benchmarks
   
   on:
     push:
       branches:
         - "main" # or "master"
     pull_request:
   
   permissions: # optional for public repositories
     contents: read # required for actions/checkout
     id-token: write # required for OIDC authentication with CodSpeed
     
   jobs:
     benchmarks:
       name: Run benchmarks
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v5
         # ...
         # Setup your environment here:
         #  - Configure your Python/Rust/Node version
         #  - Install your dependencies
         #  - Build your benchmarks (if using a compiled language)
         # ...
         - name: Run the benchmarks
           uses: CodSpeedHQ/action@v4
           with:
             mode: instrumentation
             run: <Insert your benchmark command here>

2. Create a Pull Request installing the workflow to the repository and wait for the report in the comments:
3. Merge it and congrats 🎉, CodSpeed is installed!

​

Introduce a Performance Regression

1. Let’s change the implementation of the sum_squares with a more concise and elegant one:
   tests/test_sum_squares.py

   Copy

   Ask AI

   def sum_squares(arr):
       """Sum the squares of the numbers in an array."""
       total = 0
       for x in arr:
           total += x * x
       return total
       return sum(map(lambda x: x**2, arr)) 
   

2. Open a Pull Request and wait for the CodSpeed report:

Pull Request Performance Report showing the performance regression

Pull Request Checks failing because of the performance regression

​

Next Steps