Workspace

Projeto de Exemplo

GitHub - Executar Online

O Vitest permite definir múltiplas configurações de projeto dentro de um único processo Vitest. Esse recurso é extremamente útil para configurações de monorepo, mas também pode ser empregado para executar testes com diferentes configurações, como resolve.alias, plugins ou test.browser, entre outras.

Definindo um Workspace

Um workspace deve conter um arquivo vitest.workspace ou vitest.projects em sua pasta raiz (localizado na mesma pasta do seu arquivo de configuração raiz ou, se este não existir, no diretório de trabalho atual). O Vitest suporta as extensões ts, js e json para este arquivo.

NOME

Observe que este recurso se chama workspace, não workspaces (sem "s" no final).

O arquivo de configuração do workspace deve ter uma exportação padrão com uma lista de arquivos ou padrões glob que referenciam seus projetos. Por exemplo, se você tem uma pasta chamada packages que contém seus projetos, você pode definir um workspace com este arquivo de configuração:

vitest.workspace.ts

export default ['packages/*'];

O Vitest tratará cada pasta em packages como um projeto separado, mesmo que não contenha um arquivo de configuração. A partir do Vitest 2.1, se este padrão glob corresponder a um arquivo, ele será considerado uma configuração do Vitest, mesmo que não tenha vitest em seu nome.

WARNING

O Vitest não trata o arquivo vitest.config raiz como um projeto de workspace, a menos que seja explicitamente especificado na configuração do workspace. Consequentemente, a configuração raiz afetará apenas opções globais como reporters e coverage.

Você também pode referenciar projetos através de seus arquivos de configuração:

vitest.workspace.ts

export default ['packages/*/vitest.config.{e2e,unit}.ts'];

Este padrão incluirá apenas projetos com um arquivo vitest.config que contenha e2e ou unit antes da extensão.

Você também pode definir projetos usando configuração inline. O arquivo de workspace suporta ambas as sintaxes simultaneamente.

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

// defineWorkspace oferece uma excelente experiência para desenvolvedores (DX) com dicas de tipo
export default defineWorkspace([
  // corresponde a todas as pastas e arquivos dentro da pasta `packages`
  'packages/*',
  {
    // adicione "extends" para combinar duas configurações
    extends: './vite.config.js',
    test: {
      include: ['tests/**/*.{browser}.test.{ts,js}'],
      // é recomendado definir um nome ao utilizar configurações inline
      name: 'happy-dom',
      environment: 'happy-dom',
    },
  },
  {
    test: {
      include: ['tests/**/*.{node}.test.{ts,js}'],
      name: 'node',
      environment: 'node',
    },
  },
]);

WARNING

Todos os projetos devem ter nomes únicos; caso contrário, o Vitest gerará um erro. Se um nome não for fornecido na configuração inline, o Vitest atribuirá um número automaticamente. Para configurações de projeto definidas com sintaxe glob, o Vitest usará por padrão a propriedade "name" no arquivo package.json mais próximo ou, se este não existir, o nome da pasta.

Se você não utiliza configurações inline, pode criar um pequeno arquivo JSON em seu diretório raiz:

vitest.workspace.json

["packages/*"]

Os projetos de workspace não aceitam todas as propriedades de configuração. Para maior segurança de tipos, use o método defineProject em vez de defineConfig dentro dos arquivos de configuração do projeto:

packages/a/vitest.config.ts

// @errors: 2769
import { defineProject } from 'vitest/config';

export default defineProject({
  test: {
    environment: 'jsdom',
    // "reporters" não é permitido em uma configuração de projeto,
    // então apresentará um erro
    reporters: ['json'],
  },
});

Executando testes

Para executar testes dentro do workspace, defina um script em seu package.json raiz:

{
  "scripts": {
    "test": "vitest"
  }
}

Agora os testes podem ser executados com seu gerenciador de pacotes:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Se você precisar executar testes apenas em um único projeto, utilize a opção CLI --project:

npm

npm run test --project e2e

yarn

yarn test --project e2e

pnpm

pnpm run test --project e2e

bun

bun test --project e2e

TIP

A opção CLI --project pode ser usada múltiplas vezes para filtrar por vários projetos:

npm

npm run test --project e2e --project unit

yarn

yarn test --project e2e --project unit

pnpm

pnpm run test --project e2e --project unit

bun

bun test --project e2e --project unit

Configuração

Nenhuma das opções de configuração é herdada do arquivo de configuração de nível raiz. Você pode criar um arquivo de configuração compartilhado e mesclá-lo manualmente com a configuração do projeto:

packages/a/vitest.config.ts

import { defineProject, mergeConfig } from 'vitest/config';
import configShared from '../vitest.shared.js';

export default mergeConfig(
  configShared,
  defineProject({
    test: {
      environment: 'jsdom',
    },
  })
);

No nível defineWorkspace, você pode usar a opção extends para herdar da sua configuração de nível raiz. Todas as opções serão mescladas.

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    extends: './vitest.config.ts',
    test: {
      name: 'unit',
      include: ['**/*.unit.test.ts'],
    },
  },
  {
    extends: './vitest.config.ts',
    test: {
      name: 'integration',
      include: ['**/*.integration.test.ts'],
    },
  },
]);

Algumas das opções de configuração não são permitidas em uma configuração de projeto. As principais são:

• coverage: a cobertura é realizada para todo o workspace
• reporters: apenas os reporters de nível raiz são suportados
• resolveSnapshotPath: apenas o resolvedor de nível raiz é considerado
• todas as outras opções que não afetam os executores de teste

TIP

Todas as opções de configuração que não são suportadas dentro de uma configuração de projeto são indicadas por um sinal * no guia "Config".