TestProject 3.0.0+

WARNING

Tato příručka popisuje pokročilé API pro Node.js. Pokud chcete pouze definovat projekty, postupujte podle příručky "Testovací projekty".

name

Název je unikátní řetězec, který přiřazuje uživatel nebo který je interpretován Vitestem. Pokud uživatel název neposkytne, Vitest se pokusí načíst package.json v kořenovém adresáři projektu a použije z něj vlastnost name. Pokud package.json neexistuje, Vitest ve výchozím nastavení použije název složky. Inline projekty používají jako název čísla (která jsou převedena na řetězec).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // obsahuje package.json s "@pkg/server"
      './utils', // nemá soubor package.json
      {
        // nenastavuje vlastní název
        test: {
          pool: 'threads',
        },
      },
      {
        // přizpůsobený název
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Pokud kořenový projekt není součástí uživatelských projektů, jeho name nebude rozpoznáno.

vitest

vitest odkazuje na globální proces Vitest.

serializedConfig

Toto je konfigurace, kterou testovací procesy obdrží. Vitest serializuje konfiguraci tak, že ručně odstraní všechny funkce a vlastnosti, které nelze serializovat. Jelikož je tato hodnota dostupná jak v testech, tak v prostředí Node.js, její typ je exportován z hlavního vstupního bodu.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

Vlastnost serializedConfig funguje jako getter. Pokaždé, když je k ní přistupováno, Vitest znovu serializuje konfiguraci, pokud byla změněna. To také znamená, že vždy vrací jinou referenci:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

Testovací konfigurace, se kterou byl Vitest inicializován. Pokud se jedná o kořenový projekt, globalConfig a config budou odkazovat na stejný objekt. Tato konfigurace je užitečná pro hodnoty, které nelze nastavit na úrovni projektu, jako je coverage nebo reporters.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

Toto je finální testovací konfigurace projektu.

hash 3.2.0+

Toto je unikátní hash tohoto projektu. Tato hodnota je konzistentní napříč opakovanými spuštěními.

Je založen na kořenovém adresáři projektu a jeho názvu. Všimněte si, že kořenová cesta se liší mezi různými operačními systémy, takže hash se bude také lišit.

vite

Toto je ViteDevServer projektu. Všechny projekty mají své vlastní Vite servery.

browser

Tato hodnota se nastaví pouze v případě, že testy běží v prohlížeči. Pokud je browser povolen, ale testy ještě neproběhly, bude tato hodnota undefined. Pokud potřebujete zjistit, zda projekt podporuje testy v prohlížeči, použijte metodu project.isBrowserEnabled().

WARNING

API prohlížeče je ještě experimentální a nedodržuje SemVer. API prohlížeče bude standardizováno odděleně od zbytku API.

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Způsob, jak poskytnout vlastní hodnoty testům, doplňující pole config.provide. Všechny hodnoty jsou před uložením ověřeny pomocí structuredClone, ale samotné hodnoty v providedContext nejsou klonovány.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Hodnoty mohou být poskytovány dynamicky. Poskytnutá hodnota v testech bude aktualizována při jejich dalším spuštění.

TIP

Tato metoda je také k dispozici pro globální soubory nastavení pro případy, kdy nemůžete použít veřejné API:

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

getProvidedContext

function getProvidedContext(): ProvidedContext;

Toto vrací objekt kontextu. Každý projekt také dědí globální kontext nastavený vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Hodnoty kontextu projektu vždy přepíší kontext kořenového projektu.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Vytvoří specifikaci testu, kterou lze použít v vitest.runTestSpecifications. Specifikace omezuje testovací soubor na konkrétní project a volitelné locations testu. Lokace testu jsou řádky kódu, kde je test definován ve zdrojovém kódu. Pokud jsou lokace poskytnuty, Vitest spustí pouze testy definované na těchto řádcích. Všimněte si, že pokud je definován testNamePattern, bude také aplikován.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // volitelné řádky testu
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification očekává určené ID modulu. Automaticky nenajde soubor ani nezkontroluje, zda existuje v souborovém systému.

Všimněte si také, že project.createSpecification vždy vrací novou instanci.

isRootProject

function isRootProject(): boolean;

Zkontroluje, zda je aktuální projekt kořenovým projektem. Kořenový projekt můžete také získat voláním vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Testovací soubory, které odpovídají filtrům.
   */
  testFiles: string[];
  /**
   * Soubory testů kontroly typů, které odpovídají filtrům. Toto bude prázdné, pokud `typecheck.enabled` není `true`.
   */
  typecheckTestFiles: string[];
};

Prohledá všechny testovací soubory. Tato funkce vrací objekt s běžnými testy a testy kontroly typů.

Tato metoda přijímá filters. Filtry mohou představovat pouze část cesty k souboru, na rozdíl od jiných metod na instanci Vitest:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest používá fast-glob k nalezení testovacích souborů. test.dir, test.root, root nebo process.cwd() definují volbu cwd.

Tato metoda zohledňuje několik možností konfigurace:

• test.include, test.exclude pro nalezení běžných testovacích souborů
• test.includeSource, test.exclude pro nalezení in-source testů
• test.typecheck.include, test.typecheck.exclude pro nalezení testů kontroly typů

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Tato metoda kontroluje, zda je soubor běžným testovacím souborem. Používá stejné konfigurační vlastnosti, které globTestFiles používá pro validaci.

Tato metoda také přijímá druhý parametr, kterým je zdrojový kód. Ten se používá k ověření, zda je soubor in-source testem. Pokud tuto metodu voláte opakovaně pro více projektů, doporučuje se soubor nejprve načíst a pak předat jeho obsah. Pokud soubor není testovacím souborem, ale odpovídá globu includeSource, Vitest soubor synchronně přečte, pokud není poskytnut source.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true, pokud je nastaveno `includeSource`

import

function import<T>(moduleId: string): Promise<T>

Importuje soubor pomocí Vite module runneru. Soubor bude transformován pomocí Vite s poskytnutou konfigurací projektu a spuštěn v samostatném kontextu. Všimněte si, že moduleId je relativní k config.root.

DANGER

project.import využívá stávající graf modulů Vite, takže import stejného modulu pomocí běžného importu vrátí jiný modul:

import * as staticExample from './example.js';
const dynamicExample = await project.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Interně Vitest používá tuto metodu k importu globálních nastavení, vlastních poskytovatelů pokrytí a vlastních reportérů, což znamená, že všechny tyto prvky sdílejí stejný graf modulů, pokud patří ke stejnému Vite serveru.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Toto je zkratka pro project.vitest.onTestsRerun. Přijímá callback, který bude spuštěn, když byly testy naplánovány k opětovnému spuštění (obvykle kvůli změně souboru).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Vrátí true, pokud tento projekt provádí testy v prohlížeči.

close

function close(): Promise<void>;

Uzavře projekt a všechny související zdroje. Toto lze volat pouze jednou; slib pro uzavření je uložen do mezipaměti, dokud se server nespustí znovu. Pokud jsou zdroje znovu potřeba, vytvořte nový projekt.

Podrobněji, tato metoda uzavře Vite server, zastaví službu kontroly typů, uzavře prohlížeč, pokud běží, smaže dočasný adresář, který obsahuje zdrojový kód, a resetuje poskytnutý kontext.