Quickstart

Documentation Index

Fetch the complete documentation index at: https://codspeed.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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. After connecting your repository, you can proceed to the setup to start tracking performance.

​

Setup

​

Automated setup

1. From the repository setup screen, click Start AI Setup to let the Wizard handle the configuration:
2. The Wizard analyzes your repository and configures it:
3. The Wizard opens a setup pull request:
4. Review and merge the pull request to complete setup.

​

How it works

1. Detects existing benchmarks: finds and configures your benchmarks in the language and framework you’re already using.
2. Creates benchmarks if needed: generates appropriate benchmark files when none exist in the repository.
3. Generates CI workflows: creates optimized GitHub Actions or GitLab CI configurations tailored to your setup.
4. Opens a pull request: submits all changes for your review before anything is merged.

​

Manual setup

​

Create performance tests

1. Install the CodSpeed plugin for pytest:
   pip install pytest-codspeed
   
2. Write a performance test using the @pytest.mark.benchmark marker:
   tests/test_sum_squares.py

   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:
   terminal

   $ 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 ====================
   
   Your first performance test is ready. Next, track it in CI with CodSpeed.

​

Run the tests in your CI

1. Create a new GitHub Actions workflow file to run your benchmarks:
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

   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:

​

Next Steps