From c2986946c174403b7b605d2e22682f64510f63f7 Mon Sep 17 00:00:00 2001 From: 3v0k4 Date: Fri, 20 Dec 2024 18:07:26 +0100 Subject: [PATCH] docs: vitest --- _plugins/docusaurus.rb | 9 + docusaurus/docs/cypress/troubleshooting.md | 2 + docusaurus/docs/index.mdx | 18 +- docusaurus/docs/jest/troubleshooting.md | 2 + docusaurus/docs/overview/index.mdx | 2 +- docusaurus/docs/troubleshooting/index.mdx | 8 +- docusaurus/docs/vitest/guide/index.mdx | 750 +++++++++++++++++++++ docusaurus/docs/vitest/reference.md | 240 +++++++ docusaurus/docs/vitest/troubleshooting.md | 42 ++ docusaurus/sidebars.ts | 33 + docusaurus/src/css/custom.css | 11 + docusaurus/static/img/vitest.svg | 5 + 12 files changed, 1114 insertions(+), 8 deletions(-) create mode 100644 docusaurus/docs/vitest/guide/index.mdx create mode 100644 docusaurus/docs/vitest/reference.md create mode 100644 docusaurus/docs/vitest/troubleshooting.md create mode 100644 docusaurus/static/img/vitest.svg diff --git a/_plugins/docusaurus.rb b/_plugins/docusaurus.rb index 8d17a0c8..8320b7ad 100644 --- a/_plugins/docusaurus.rb +++ b/_plugins/docusaurus.rb @@ -41,6 +41,15 @@ def system!(*args) system!("mkdir -p _site/jest/troubleshooting") system!("cp docusaurus/build/jest/troubleshooting/index.html _site/jest/troubleshooting") + system!("mkdir -p _site/vitest/guide") + system!("cp docusaurus/build/vitest/guide/index.html _site/vitest/guide") + + system!("mkdir -p _site/vitest/reference") + system!("cp docusaurus/build/vitest/reference/index.html _site/vitest/reference") + + system!("mkdir -p _site/vitest/troubleshooting") + system!("cp docusaurus/build/vitest/troubleshooting/index.html _site/vitest/troubleshooting") + system!("mkdir -p _site/integration") system!("cp docusaurus/build/integration/index.html _site/integration") # redirect to / system!("cp docusaurus/build/index.html _site") diff --git a/docusaurus/docs/cypress/troubleshooting.md b/docusaurus/docs/cypress/troubleshooting.md index fcb7e7af..15242846 100644 --- a/docusaurus/docs/cypress/troubleshooting.md +++ b/docusaurus/docs/cypress/troubleshooting.md @@ -36,6 +36,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/index.mdx b/docusaurus/docs/index.mdx index f03f0da6..c9e3829f 100644 --- a/docusaurus/docs/index.mdx +++ b/docusaurus/docs/index.mdx @@ -5,6 +5,7 @@ pagination_next: overview/index import api from "@site/static/img/api.png"; import javascript from "@site/static/img/javascript.png" +import Vitest from "@site/static/img/vitest.svg" import jest from "@site/static/img/jest.jpg" import cypress from "@site/static/img/cypress.jpg" import ruby from "@site/static/img/ruby.png" @@ -20,15 +21,15 @@ If you have questions, feel free to [contact us](https://knapsackpro.com/contact ## Overview
- -
+ +

Knapsack Overview
## Libraries -
+

Ruby

@@ -43,6 +44,11 @@ If you have questions, feel free to [contact us](https://knapsackpro.com/contact

Jest

 + + +
+

Vitest

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

JavaScript / TypeScript

 - +

Other Language

 @@ -66,7 +72,7 @@ You can still use Knapsack Pro by writing your integration on top of the JavaScr ## Troubleshooting
- +

Troubleshooting

 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/guide/index.mdx b/docusaurus/docs/vitest/guide/index.mdx new file mode 100644 index 00000000..96227fd2 --- /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) page 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..4e275b56 --- /dev/null +++ b/docusaurus/docs/vitest/reference.md @@ -0,0 +1,240 @@ +--- +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 --coverage +``` + +## `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 writes coverage reports. + +Default: if not specified, it falls back to [Vitest `coverage.reportsDirectory`](https://vitest.dev/config/#coverage-reportsdirectory) + +## `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: if not specified, it falls back to [Vitest `exclude`](https://vitest.dev/config/#exclude) + +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. + +::: + +Run tests matching a pattern. It can be used in tandem with `KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN`. + +Default: if not specified, it falls back to [Vitest `include`](https://vitest.dev/config/#include) + +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..422b368f --- /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="**/*.{test,spec}.?(c|m)[jt]s?(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..16840893 100644 --- a/docusaurus/sidebars.ts +++ b/docusaurus/sidebars.ts @@ -223,6 +223,39 @@ 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: "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 @@ + + + + +