Can't see your language/testing framework above? [Let us know](https://docs.google.com/forms/d/e/1FAIpQLSe7Z6k__VczmRMmXykjA5i2MVEA3nEJ90gbiIeCRjecWhPOig/viewform?hl=en).
@@ -52,12 +58,12 @@ Can't see your language/testing framework above? [Let us know](https://docs.goog
You can still use Knapsack Pro by writing your integration on top of the JavaScript SDK or using the Knapsack Pro API:
diff --git a/docusaurus/docs/jest/troubleshooting.md b/docusaurus/docs/jest/troubleshooting.md
index 1a599de9..916735d2 100644
--- a/docusaurus/docs/jest/troubleshooting.md
+++ b/docusaurus/docs/jest/troubleshooting.md
@@ -27,6 +27,8 @@ export NODE_OPTIONS=--max_old_space_size=4096
npx knapsack-pro-jest
npx knapsack-pro-cypress
+
+npx knapsack-pro-vitest
```
## Debug Knapsack Pro on your development environment/machine
diff --git a/docusaurus/docs/overview/index.mdx b/docusaurus/docs/overview/index.mdx
index e63ec7d0..17689b2f 100644
--- a/docusaurus/docs/overview/index.mdx
+++ b/docusaurus/docs/overview/index.mdx
@@ -20,7 +20,7 @@ Knapsack Pro wraps your current test runner(s) and works with your existing CI i
- Tracks your CI builds to detect bottlenecks
- Does not have access to your source code and collects minimal test data (with opt-in encryption)
- Enables you to export historical metrics about your CI builds
-- Supports out-of-the-box any Ruby test runners, Cypress, Jest (and provides both SDK and API to integrate with any other language)
+- Supports out-of-the-box any Ruby test runners, Cypress, Jest, Vitest (and provides both SDK and API to integrate with any other language)
- Replaces local dependencies like Redis with an API and runs your tests regardless of network problems
diff --git a/docusaurus/docs/troubleshooting/index.mdx b/docusaurus/docs/troubleshooting/index.mdx
index 4cfb810a..a7b57694 100644
--- a/docusaurus/docs/troubleshooting/index.mdx
+++ b/docusaurus/docs/troubleshooting/index.mdx
@@ -6,6 +6,7 @@ pagination_next: null
import ruby from "@site/static/img/ruby.png"
import cypress from "@site/static/img/cypress.jpg"
import jest from "@site/static/img/jest.jpg"
+import Vitest from "@site/static/img/vitest.svg"
# Troubleshooting
@@ -15,7 +16,7 @@ If you are utilizing two CI providers simultaneously, for example, CircleCI and
## Troubleshooting libraries
-
diff --git a/docusaurus/docs/vitest/cookbook.md b/docusaurus/docs/vitest/cookbook.md
new file mode 100644
index 00000000..e735dd0f
--- /dev/null
+++ b/docusaurus/docs/vitest/cookbook.md
@@ -0,0 +1,45 @@
+---
+pagination_next: null
+pagination_prev: null
+---
+
+# Vitest Cookbook
+
+cli args vitest supported?
+what needs to be done for coverage KNAPSACK_PRO_COVERAGE_DIRECTORY and --coverage and config? https://github.com/KnapsackPro/knapsack-pro-js/blob/main/packages/vitest-example-test-suite/vitest.config.ts
+
+## Use a Jest config file
+
+:::caution
+
+To filter tests use [`KNAPSACK_PRO_TEST_FILE_PATTERN`](reference.md#knapsack_pro_test_file_pattern).
+
+:::
+
+You can pass it with a [command-line argument](reference.md#command-line-arguments):
+
+```bash
+npx knapsack-pro-jest --config=jest.config.e2e.js
+```
+
+## Generate code coverage reports
+
+```bash
+export KNAPSACK_PRO_COVERAGE_DIRECTORY=coverage
+
+npx knapsack-pro-jest --coverage
+```
+
+Knapsack Pro will generate one coverage report for each batch of tests executed on the CI node. To merge the reports you may consider [this script](https://github.com/facebook/jest/issues/2418#issuecomment-478932514).
+
+## Generate XML reports
+
+You can generate [jest-junit](https://github.com/jest-community/jest-junit) reports with:
+
+```bash
+export JEST_JUNIT_UNIQUE_OUTPUT_NAME=true
+
+npx knapsack-pro-jest --ci --reporters=jest-junit
+```
+
+Knapsack Pro will generate one XML reports for each batch of tests executed on the CI node. Some CI providers (e.g., GitLab CI) can merge multiple XML files from parallel CI nodes.
diff --git a/docusaurus/docs/vitest/guide/index.mdx b/docusaurus/docs/vitest/guide/index.mdx
new file mode 100644
index 00000000..5dadcd0d
--- /dev/null
+++ b/docusaurus/docs/vitest/guide/index.mdx
@@ -0,0 +1,750 @@
+---
+toc_max_heading_level: 2
+pagination_next: null
+pagination_prev: null
+---
+
+import { RadioGroup } from '@site/src/components/RadioGroup'
+import { ShowIfSearchParam, ShowIfSearchParamAndValue } from '@site/src/components/ShowIf'
+import { DelayHashNavigation } from '@site/src/components/DelayHashNavigation'
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Knapsack Pro Vitest: Quickstart
+
+
+
+[Create an account](https://knapsackpro.com?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide) to generate API tokens and use Knapsack Pro.
+
+## Installation
+
+Make sure you have `vitest` in your `package.json` because `@knapsack-pro/vitest` uses the version installed in your project.
+
+
+
+
+```bash
+npm install --save-dev @knapsack-pro/vitest
+```
+
+
+
+
+```bash
+yarn add --dev @knapsack-pro/vitest
+```
+
+
+
+
+Now, fill in the following form to generate the instruction steps for your project:
+
+**What is your CI provider?**
+
+
+## Instructions
+
+
+
+### AppVeyor
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_appveyor) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+For each parallel job, define:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index)
+
+Remember to configure the number of parallel CI nodes in AppVeyor.
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=0 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=1 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=N-1 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+
+
+
+
+### Buildkite
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_buildkite) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Remember to configure the `parallelism` parameter in your build step.
+
+
+
+
+```bash
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+npx knapsack-pro-vitest
+```
+
+
+
+
+When using the `docker-compose` plugin on Buildkite, you have to pass the following environment variables:
+
+```yaml
+steps:
+ - label: "Test"
+ parallelism: 2
+ plugins:
+ - docker-compose#3.0.3:
+ run: app
+ # highlight-next-line
+ command: npx knapsack-pro-vitest
+ config: docker-compose.test.yml
+ # highlight-start
+ env:
+ - BUILDKITE
+ - BUILDKITE_PARALLEL_JOB_COUNT
+ - BUILDKITE_PARALLEL_JOB
+ - BUILDKITE_BUILD_NUMBER
+ - BUILDKITE_COMMIT
+ - BUILDKITE_BRANCH
+ - BUILDKITE_BUILD_AUTHOR
+ - BUILDKITE_BUILD_CREATOR
+ # highlight-end
+```
+
+Here you can find an article on [how to set up a new pipeline for your project in Buildkite and configure Knapsack Pro](https://docs.knapsackpro.com/2017/auto-balancing-7-hours-tests-between-100-parallel-jobs-on-ci-buildkite-example).
+
+You can also check out the following example repositories for Ruby on Rails projects:
+
+- [Buildkite Rails Parallel Example with Knapsack Pro](https://github.com/KnapsackPro/buildkite-rails-parallel-example-with-knapsack_pro)
+- [Buildkite Rails Docker Parallel Example with Knapsack Pro](https://github.com/KnapsackPro/buildkite-rails-docker-parallel-example-with-knapsack_pro)
+
+
+
+
+
+### CircleCI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_circleci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Remember to add additional parallel containers in the CircleCI settings.
+
+```yaml title=".circleci/config.yml"
+jobs:
+ build:
+ # highlight-next-line
+ parallelism: 2
+
+ steps:
+ - checkout
+
+ # ...
+
+ # highlight-start
+ - run:
+ name: vitest with @knapsack-pro/vitest
+ command: npx knapsack-pro-vitest
+ # highlight-end
+```
+
+Here you can find an example of a [Rails project config on CircleCI 2.0](https://docs.knapsackpro.com/2017/circleci-2-0-capybara-feature-specs-selenium-webdriver-with-chrome-headless).
+
+
+
+
+
+### Cirrus CI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_cirrusci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Configure the number of parallel CI nodes with the [matrix modification](https://cirrus-ci.org/guide/writing-tasks/#matrix-modification):
+
+```yaml title=".cirrus.yml"
+task:
+ environment:
+ KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST: ENCRYPTED[KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST]
+ matrix:
+ name: CI Node 0
+ name: CI Node 1
+ name: CI Node 2
+ test_script:
+ - npx knapsack-pro-vitest
+```
+
+Remember to set up the `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` as an [encrypted variable](https://cirrus-ci.org/guide/writing-tasks/#encrypted-variables).
+
+Here is an example of a [`.cirrus.yml` configuration file](https://cirrus-ci.org/examples/#ruby) for a Ruby project.
+
+
+
+
+
+### CloudBees CodeShip
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_codeship) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+For each [parallel pipeline](https://documentation.codeship.com/basic/builds-and-configuration/parallel-tests/#using-parallel-test-pipelines), define:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index)
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=0 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=1 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=N-1 \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+Consider moving the `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` to the _Environment_ page of your project settings in CodeShip.
+
+
+
+
+
+### Codefresh
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_codefresh) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define in `.codefresh/codefresh.yml`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index)
+ - In the `matrix` section, list all the `KNAPSACK_PRO_CI_NODE_INDEX`es (from `0` to `KNAPSACK_PRO_CI_NODE_TOTAL-1`).
+
+Remember to configure the YAML file path on Codefresh: _Pipelines > Settings (cog icon next to the pipeline) > Workflow Tab (horizontal menu on the top) > Path to YAML > `./.codefresh/codefresh.yml`_.
+
+Here's an example config:
+
+
+
+
+```yaml title=".codefresh/codefresh.yml"
+version: "1.0"
+
+stages:
+ - "clone"
+ - "build"
+ - "tests"
+
+steps:
+ main_clone:
+ type: "git-clone"
+ description: "Cloning main repository..."
+ repo: "${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}"
+ revision: "${{CF_BRANCH}}"
+ stage: "clone"
+ BuildTestDockerImage:
+ title: Building Test Docker image
+ type: build
+ arguments:
+ image_name: "${{CF_ACCOUNT}}/${{CF_REPO_NAME}}-test"
+ tag: "${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}"
+ dockerfile: Test.Dockerfile
+ stage: "build"
+
+ run_tests:
+ stage: "tests"
+ image: "${{BuildTestDockerImage}}"
+ working_directory: /src
+ fail_fast: false
+ environment:
+ # highlight-next-line
+ - KNAPSACK_PRO_CI_NODE_TOTAL=2
+ # highlight-start
+ matrix:
+ environment:
+ - KNAPSACK_PRO_CI_NODE_INDEX=0
+ - KNAPSACK_PRO_CI_NODE_INDEX=1
+ # highlight-end
+ commands:
+ # highlight-start
+ - npx knapsack-pro-vitest
+ # highlight-end
+```
+
+Consider setting up the `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` on the Codefresh dashboard: _Pipelines > Settings (cog icon next to the pipeline) > Variables Tab (vertical menu on the right-hand side)_.
+
+
+
+
+
+```bash title="Test.Dockerfile"
+FROM node:10.13
+
+RUN apt-get update && \
+ apt-get install -y \
+ python3-dev \
+ python3-pip
+
+# Install AWS CLI
+RUN pip3 install awscli
+
+# Install Codefresh CLI
+RUN wget https://github.com/codefresh-io/cli/releases/download/v0.31.1/codefresh-v0.31.1-alpine-x64.tar.gz
+RUN tar -xf codefresh-v0.31.1-alpine-x64.tar.gz -C /usr/local/bin/
+
+COPY . /src
+
+WORKDIR /src
+
+RUN npm install
+```
+
+
+
+
+
+
+
+
+### GitHub Actions
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_githubactions) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define in `.github/workflows/main.yaml`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest) in _GitHub Settings > Secrets_ as described in [GitHub Actions' docs](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total) using the [`matrix` property](https://help.github.com/en/articles/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index) using the [`matrix` property](https://help.github.com/en/articles/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)
+
+Here's an example config:
+
+```yaml title=".github/workflows/main.yaml"
+name: Main
+
+on: [push]
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+
+ strategy:
+ fail-fast: false
+ # highlight-start
+ matrix:
+ node-version: [18.x]
+ ci_node_total: [2]
+ ci_node_index: [0, 1]
+ # highlight-end
+
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: Set up Node
+ uses: actions/setup-node@v1
+ with:
+ node-version: ${{ matrix.node-version }}
+
+ - name: Install and Build
+ run: |
+ npm install
+ npm run build --if-present
+
+ # highlight-start
+ - name: Run tests
+ env:
+ KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST: ${{ secrets.KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST }}
+ KNAPSACK_PRO_CI_NODE_TOTAL: ${{ matrix.ci_node_total }}
+ KNAPSACK_PRO_CI_NODE_INDEX: ${{ matrix.ci_node_index }}
+ run: |
+ npx knapsack-pro-vitest
+ # highlight-end
+```
+
+
+
+
+
+### GitLab CI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_gitlabci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+#### GitLab CI >= 11.5
+
+```yaml
+test:
+ parallel: 2
+
+ script:
+ - KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN npx knapsack-pro-vitest
+```
+
+See also [how to configure running parallel CI nodes in GitLab](https://docs.gitlab.com/ee/ci/yaml/#parallel).
+
+#### GitLab CI < 11.5
+
+Define in `.gitlab-ci.yml`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index)
+
+Here's an example configuration for 2 parallel jobs:
+
+```yaml title=".gitlab-ci.yml"
+stages:
+ - test
+
+# highlight-start
+variables:
+ KNAPSACK_PRO_CI_NODE_TOTAL: 2
+# highlight-end
+
+test_ci_first_node:
+ stage: test
+ script:
+ # highlight-start
+ - export KNAPSACK_PRO_CI_NODE_INDEX=0
+ - KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN npx knapsack-pro-vitest
+ # highlight-end
+
+test_ci_second_node:
+ stage: test
+ script:
+ # highlight-start
+ - export KNAPSACK_PRO_CI_NODE_INDEX=1
+ - KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN npx knapsack-pro-vitest
+ # highlight-end
+```
+
+Remember to set up the `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` as [Secret Variables](https://gitlab.com/help/ci/variables/README.md#secret-variables) in GitLab CI: _Settings > CI/CD Pipelines > Secret Variables_.
+
+
+
+
+
+### Heroku CI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_herokuci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define in `app.json`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- `quantity`: number of parallel dynos
+- `test`: the Knapsack Pro command
+
+```json title="app.json"
+{
+ "environments": {
+ "test": {
+ "formation": {
+ "test": {
+ // highlight-next-line
+ "quantity": 2
+ }
+ },
+ "addons": [
+ "heroku-postgresql:in-dyno",
+ "heroku-redis:in-dyno"
+ ],
+ // highlight-start
+ "scripts": {
+ "test": "npx knapsack-pro-vitest"
+ },
+ "env": {
+ "KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST": "MY_VITEST_API_TOKEN"
+ }
+ // highlight-end
+ }
+ }
+}
+```
+
+Remember to set up the `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` outside of `app.json` in your Heroku CI pipeline's settings.
+
+
+
+
+
+### Jenkins
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_jenkins) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+In order to run parallel jobs with Jenkins you should use Jenkins Pipeline as described in [Parallelism and Distributed Builds with Jenkins](https://www.cloudbees.com/blog/parallelism-and-distributed-builds-jenkins).
+
+Here is an example of a `Jenkinsfile` working with Jenkins Pipeline:
+
+```groovy
+timeout(time: 60, unit: 'MINUTES') {
+ node() {
+ stage('Checkout') {
+ checkout([/* checkout code from git */])
+
+ // determine git commit hash because we need to pass it to Knapsack Pro
+ COMMIT_HASH = sh(returnStdout: true, script: 'git rev-parse HEAD').trim()
+
+ stash 'source'
+ }
+ }
+
+ // highlight-next-line
+ def num_nodes = 4; // define your total number of CI nodes (how many parallel jobs will be executed)
+ def nodes = [:]
+
+ for (int i = 0; i < num_nodes; i++) {
+ def index = i;
+ nodes["ci_node_${i}"] = {
+ node() {
+ stage('Setup') {
+ unstash 'source'
+ // other setup steps
+ }
+
+ // highlight-start
+ def knapsack_options = """\
+ KNAPSACK_PRO_CI_NODE_TOTAL=${num_nodes}\
+ KNAPSACK_PRO_CI_NODE_INDEX=${index}\
+ KNAPSACK_PRO_COMMIT_HASH=${COMMIT_HASH}\
+ KNAPSACK_PRO_BRANCH=${env.BRANCH_NAME}\
+ KNAPSACK_PRO_CI_NODE_BUILD_ID=${env.BUILD_TAG}\
+ KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN
+ """
+
+ stage('Run tests') {
+ sh """${knapsack_options} npx knapsack-pro-vitest"""
+ }
+ // highlight-end
+ }
+ }
+ }
+
+ parallel nodes // run CI nodes in parallel
+}
+```
+
+Consider setting up the `KNAPSACK_PRO_TEST_SUITE_TOKEN_*` as global environment variables in Jenkins.
+
+
+
+
+
+### Semaphore CI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_semaphoreci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define in `.semaphore/semaphore.yml`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- `parallelism`
+
+Here's an example config:
+
+```yaml title=".semaphore/semaphore.yml"
+version: v1.0
+
+name: My app
+
+agent:
+ machine:
+ type: e1-standard-2
+ os_image: ubuntu1804
+
+blocks:
+ - name: Vitest tests
+ task:
+ env_vars:
+ # highlight-start
+ - name: KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST
+ value: MY_VITEST_API_TOKEN
+ # highlight-end
+ prologue:
+ commands:
+ - checkout
+ - nvm install --lts hydrogen
+ - sem-version node --lts hydrogen
+
+ # highlight-start
+ jobs:
+ - name: Run tests with Knapsack Pro
+ parallelism: 2
+ commands:
+ - npx knapsack-pro-vitest
+ # highlight-end
+```
+
+Remember to set up `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` as a [secret](https://docs.semaphoreci.com/using-semaphore/secrets).
+
+
+
+
+
+### Travis CI
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_travisci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define in `.travis.yml`:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index) as [jobs](http://docs.travis-ci.com/user/speeding-up-the-build/#parallelizing-your-builds-across-virtual-machines)
+
+```yaml
+script:
+ - "npx knapsack-pro-vitest"
+
+env:
+ global:
+ - KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN
+ - KNAPSACK_PRO_CI_NODE_TOTAL=3
+ jobs:
+ - KNAPSACK_PRO_CI_NODE_INDEX=0
+ - KNAPSACK_PRO_CI_NODE_INDEX=1
+ - KNAPSACK_PRO_CI_NODE_INDEX=2
+```
+
+Remember to set up `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST` as tokens in the Travis settings to avoid exposing them in the build logs.
+
+You can find more info about the global and matrix env configuration in the [Travis' docs](https://docs.travis-ci.com/user/customizing-the-build/#build-matrix).
+
+
+
+
+
+### Other CI provider
+
+[Generate an API token](https://knapsackpro.com/dashboard?utm_source=docs_knapsackpro&utm_medium=page&utm_campaign=knapsack-pro-vitest&utm_content=installation_guide_otherci) for each Knapsack Pro command on the CI. Each command needs its own API token to treat every test suite as a separate entity.
+
+Define the following global environment variables on your CI server:
+
+- [`KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`](../reference.md#knapsack_pro_test_suite_token_vitest)
+- [`KNAPSACK_PRO_CI_NODE_TOTAL`](../reference.md#knapsack_pro_ci_node_total)
+- [`KNAPSACK_PRO_CI_NODE_INDEX`](../reference.md#knapsack_pro_ci_node_index)
+- [`KNAPSACK_PRO_CI_NODE_BUILD_ID`](../reference.md#knapsack_pro_ci_node_build_id)
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=0 \
+KNAPSACK_PRO_CI_NODE_BUILD_ID=MY_BUILD_ID \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=1 \
+KNAPSACK_PRO_CI_NODE_BUILD_ID=MY_BUILD_ID \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+```bash
+KNAPSACK_PRO_CI_NODE_TOTAL=N \
+KNAPSACK_PRO_CI_NODE_INDEX=N-1 \
+KNAPSACK_PRO_CI_NODE_BUILD_ID=MY_BUILD_ID \
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+npx knapsack-pro-vitest
+```
+
+
+
+
+
+
+
+
+### Verify that everything works
+
+Push a new commit to your repository and visit your [dashboard](https://knapsackpro.com/dashboard) to make sure all your CI nodes were recorded successfully in _Show build metrics > Show (build)_.
+
+**Congratulations!** Now that Knapsack Pro knows the statistics of your test suite, your CI builds will be parallelized optimally.
+
+### Next up
+
+Make sure you check out the [Reference](../reference.md) and [Cookbook](../cookbook.md) pages to fine-tune your Knapsack Pro setup.
+
+
+
+## Need help?
+
+[Get in touch!](https://knapsackpro.com/contact)
+
+We have helped TONS of teams and seen TONS of projects. We know each test suite is a different beast and we'd be happy to help you set up Knapsack Pro.
diff --git a/docusaurus/docs/vitest/reference.md b/docusaurus/docs/vitest/reference.md
new file mode 100644
index 00000000..0122e0c1
--- /dev/null
+++ b/docusaurus/docs/vitest/reference.md
@@ -0,0 +1,248 @@
+---
+pagination_next: null
+pagination_prev: null
+toc_max_heading_level: 2
+---
+
+# Vitest Reference
+
+You can configure things in two ways:
+
+- Command-line arguments for the test runner
+- Environment variables for Knapsack Pro or Node
+
+Unless specified otherwise, everything on this page is environment variables.
+
+## Command-line arguments
+
+You can pass all the [supported Vitest CLI options](https://vitest.dev/guide/cli.html) as command-line arguments:
+
+```bash
+npx knapsack-pro-vitest --verbose
+```
+
+## `KNAPSACK_PRO_BRANCH`
+
+Git branch under test.
+
+You don't need to set it if either:
+
+- Your CI is one of the [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers)
+- Your CI has git installed so that Knapsack Pro can retrieve it
+
+In some cases, particularly for pull request merge commits or if the CI provider checks out a specific git commit during the build process, Git might only expose `HEAD` instead of the actual branch name.
+
+## `KNAPSACK_PRO_CI_NODE_BUILD_ID`
+
+Unique ID that identifies a CI build. It must be the same for all the parallel CI nodes.
+
+Default: Knapsack Pro will take it from the CI environment (see [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers))
+
+If your CI is not supported, you may generate a build ID with `KNAPSACK_PRO_CI_NODE_BUILD_ID=$(openssl rand -base64 32)` and make it available to all parallel nodes.
+
+## `KNAPSACK_PRO_CI_NODE_INDEX`
+
+Index of current CI node (first should be 0, second should be 1, etc.).
+
+Default: Knapsack Pro will take it from the CI environment (see [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers))
+
+If your CI is not supported, you need to set it manually.
+
+## `KNAPSACK_PRO_CI_NODE_RETRY_COUNT`
+
+A retry count of the current CI node in case of a single node/job retry.
+
+There is no need to set this for the following CI providers that are supported out of the box:
+
+* GitHub Actions
+* Buildkite
+
+For other CI providers:
+
+If you use `KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true`, you need to set `KNAPSACK_PRO_CI_NODE_RETRY_COUNT=1` when retrying a single node to disable Fallback Mode. Otherwise, the CI node would use a different (fallback) split and run a different subset of tests when the API cannot be reached.
+
+Default: `0` (or an environment variable for supported CI providers)
+
+Available:
+
+- `0`: Fallback Mode is enabled
+- `> 0`: Fallback Mode is disabled and Knapsack Pro raises an error if the API cannot be reached
+
+## `KNAPSACK_PRO_CI_NODE_TOTAL`
+
+Total number of parallel CI nodes.
+
+Default: Knapsack Pro will take it from the CI environment (see [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers))
+
+If your CI is not supported, you need to set it manually.
+
+## `KNAPSACK_PRO_COMMIT_HASH`
+
+Hash of the commit under test.
+
+You don't need to set it if either:
+
+- Your CI is one of the [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers)
+- Your CI has git installed so that Knapsack Pro can retrieve it
+
+## `KNAPSACK_PRO_COVERAGE_DIRECTORY`
+
+The directory where Vitest should output its coverage files.
+
+Default: `undefined`
+
+Read more on [Generate code coverage reports](cookbook.md#generate-code-coverage-reports).
+
+## `KNAPSACK_PRO_ENDPOINT` (Internal)
+
+Default: `https://api.knapsackpro.com`
+
+## `KNAPSACK_PRO_FIXED_QUEUE_SPLIT`
+
+Dynamic or fixed tests split when retrying a CI build.
+
+Default: automagically set to the correct value for your [CI provider](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers)
+
+Available:
+
+- `false`: generate a new split when `KNAPSACK_PRO_CI_NODE_BUILD_ID` changes (see what Knapsack Pro uses as `ciNodeBuildId` for your [CI provider](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers))
+- `true`: if the triplet `(branch name, commit hash, number of nodes)` was already split in a previous build use the same split, otherwise generate a new split
+
+Recommended:
+
+- `true` when your CI allows retrying single CI nodes (e.g., Buildkite, GitHub Actions) or if your CI nodes are spot instances/preemptible
+- `true` when your CI uses the same `KNAPSACK_PRO_CI_NODE_BUILD_ID` on retries (e.g., GitHub Actions, Travis, CodeShip)
+- `false` otherwise
+
+## `KNAPSACK_PRO_LOG_LEVEL`
+
+Default: `info`
+
+Available:
+
+- `error`: critical errors
+- `warn`: warnings (e.g. Fallback Mode has started)
+- `info`: Knapsack Pro API request response body
+- `verbose`
+- `debug`: Knapsack Pro API request headers and body
+- `silly`
+
+## `KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN`
+
+Exclude tests matching a pattern. It can be used in tandem with `KNAPSACK_PRO_TEST_FILE_PATTERN`.
+
+Default: `undefined`
+
+Available: anything that [node-glob](https://github.com/isaacs/node-glob#glob-primer) accepts
+
+Hint: you can debug in `node`
+
+```js
+var glob = require("glob");
+var MY_GLOB = "{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}";
+glob(MY_GLOB, {}, function (err, files) {
+ console.log(files);
+});
+```
+
+Examples:
+
+```bash
+KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"
+# or
+KNAPSACK_PRO_TEST_FILE_PATTERN=="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}" \
+KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"
+```
+
+## `KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE`
+
+File containing the list of **relative paths** of tests to run. When `KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE` is set, both `KNAPSACK_PRO_TEST_FILE_PATTERN` and `KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN` are ignored.
+
+Default: `undefined`
+
+Example:
+
+```bash
+KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE=__tests__/fixtures/list.txt
+
+# ✅ list.txt
+__tests__/a.test.js
+__tests__/b.test.js
+__tests__/c.test.js
+
+# ⛔️ list.txt
+/home/user123/project/__tests__/a.test.js
+/home/user123/project/__tests__/b.test.js
+/home/user123/project/__tests__/c.test.js
+```
+
+## `KNAPSACK_PRO_TEST_FILE_PATTERN`
+
+:::caution
+
+Make sure to match individual files by adding the suffix (e.g., `.js`) so that Knapsack Pro can split by file and not by directory.
+
+:::
+
+:::caution
+
+Knapsack Pro ignores patterns specified as Vitest CLI arguments or Vitest config files.
+
+:::
+
+Run tests matching a pattern. It can be used in tandem with `KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN`.
+
+Default: `"{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}"`
+
+Available: anything that [node-glob](https://github.com/isaacs/node-glob#glob-primer) accepts
+
+Hint: you can debug in `node`
+
+```js
+var glob = require("glob");
+var MY_GLOB = "{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}";
+glob(MY_GLOB, {}, function (err, files) {
+ console.log(files);
+});
+```
+
+Examples:
+
+```bash
+KNAPSACK_PRO_TEST_FILE_PATTERN=="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}"
+# or
+KNAPSACK_PRO_TEST_FILE_PATTERN=="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}" \
+KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"
+```
+
+## `KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST`
+
+API token required to run Knapsack Pro.
+
+Each Knapsack Pro command defined on CI should use an individual API token.
+
+Example:
+
+```bash
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
+KNAPSACK_PRO_TEST_FILE_PATTERN=="src/user/__tests__/**/*.js" \
+ npx knapsack-pro-vitest
+
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_OTHER_VITEST_API_TOKEN \
+KNAPSACK_PRO_TEST_FILE_PATTERN=="src/admin/__tests__/**/*.js" \
+ npx knapsack-pro-vitest
+```
+
+## `KNAPSACK_PRO_USER_SEAT`
+
+A user name that started the CI build. It is usually the same person that made the git commit.
+
+You don't need to set it if:
+
+- Your CI is one of the [supported CIs](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers), and we can read the user seat for the given CI provider.
+
+Examples:
+
+```bash
+KNAPSACK_PRO_USER_SEAT="John Doe "
+```
diff --git a/docusaurus/docs/vitest/troubleshooting.md b/docusaurus/docs/vitest/troubleshooting.md
new file mode 100644
index 00000000..3c40ddef
--- /dev/null
+++ b/docusaurus/docs/vitest/troubleshooting.md
@@ -0,0 +1,42 @@
+---
+pagination_next: null
+pagination_prev: null
+---
+
+# Vitest Troubleshooting
+
+## JavaScript heap out of memory
+
+You can increase the memory available to Node with [`--max_old_space_size`](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes):
+
+```bash
+export NODE_OPTIONS=--max_old_space_size=4096
+
+npx knapsack-pro-jest
+
+npx knapsack-pro-cypress
+
+npx knapsack-pro-vitest
+```
+
+## Debug Knapsack Pro on your development environment/machine
+
+To reproduce what Knapsack Pro executed on a specific CI node, check out the same branch and run:
+
+```bash
+KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_TOKEN \
+KNAPSACK_PRO_CI_NODE_INDEX=MY_INDEX \
+KNAPSACK_PRO_CI_NODE_TOTAL=MY_TOTAL \
+KNAPSACK_PRO_BRANCH=MY_BRANCH \
+KNAPSACK_PRO_COMMIT_HASH=MY_COMMIT \
+KNAPSACK_PRO_CI_NODE_BUILD_ID=MY_BUILD_ID \
+KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true \
+KNAPSACK_PRO_TEST_FILE_PATTERN="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}" \
+npx knapsack-pro-vitest
+```
+
+`KNAPSACK_PRO_CI_NODE_BUILD_ID` must be the same as the CI build you are trying to reproduce (if it helps, take a look at what Knapsack Pro uses as `ciNodeBuildId` for your [CI provider](https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/core/src/ci-providers)).
+
+## No tests are executed (or `test_files: [ 'parameter is required' ]`)
+
+Make sure [`KNAPSACK_PRO_TEST_FILE_PATTERN`](reference.md#knapsack_pro_test_file_pattern) is correct.
diff --git a/docusaurus/sidebars.ts b/docusaurus/sidebars.ts
index 7984db55..77849632 100644
--- a/docusaurus/sidebars.ts
+++ b/docusaurus/sidebars.ts
@@ -223,6 +223,44 @@ const sidebars: SidebarsConfig = {
},
],
},
+ {
+ type: "category",
+ label: "Vitest",
+ collapsible: true,
+ collapsed: true,
+ items: [
+ {
+ type: "doc",
+ label: "Installation",
+ id: "vitest/guide/index",
+ },
+ {
+ type: "doc",
+ label: "Reference",
+ id: "vitest/reference",
+ },
+ {
+ type: "doc",
+ label: "Troubleshooting",
+ id: "vitest/troubleshooting",
+ },
+ {
+ type: "doc",
+ label: "Cookbook",
+ id: "vitest/cookbook",
+ },
+ {
+ type: "link",
+ label: "GitHub",
+ href: "https://github.com/KnapsackPro/knapsack-pro-js/tree/main/packages/vitest",
+ },
+ {
+ type: "link",
+ label: "Changelog",
+ href: "https://github.com/KnapsackPro/knapsack-pro-js/blob/main/packages/vitest/CHANGELOG.md",
+ },
+ ],
+ },
{
type: "category",
label: "Write your integration",
diff --git a/docusaurus/src/css/custom.css b/docusaurus/src/css/custom.css
index 4235c992..c2893026 100644
--- a/docusaurus/src/css/custom.css
+++ b/docusaurus/src/css/custom.css
@@ -126,6 +126,14 @@ div[class^='announcementBar_'] {
margin-bottom: var(--ifm-paragraph-margin-bottom);
}
+.grid-4 {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(215px, 1fr));
+ gap: 10px;
+ margin-bottom: var(--ifm-paragraph-margin-bottom);
+}
+
+
.cell {
align-items: center;
border-radius: 10px;
@@ -135,6 +143,9 @@ div[class^='announcementBar_'] {
flex-shrink: 0;
gap: 20px;
padding: 10px 20px;
+}
+
+.cell--fixed {
width: 265px;
}
diff --git a/docusaurus/static/img/vitest.svg b/docusaurus/static/img/vitest.svg
new file mode 100644
index 00000000..e52875fd
--- /dev/null
+++ b/docusaurus/static/img/vitest.svg
@@ -0,0 +1,5 @@
+