Průvodce migrací

Migrace na Vitest 3.0

Možnosti testování jako třetí argument

Vitest 3.0 vypíše varování, pokud předáte objekt jako třetí argument funkcím test nebo describe:

test('validation works', () => {
  // ...
}, { retry: 3 }); 

test('validation works', { retry: 3 }, () => { 
  // ...
});

Další hlavní verze vyhodí chybu, pokud je třetí argument objektem. Všimněte si, že číslo časového limitu není zastaralé.

test('validation works', () => {
  // ...
}, 1000); // Ok ✅

browser.name a browser.providerOptions jsou zastaralé

Obě možnosti browser.name a browser.providerOptions budou odstraněny ve Vitest 4. Místo nich použijte novou možnost browser.instances:

export default defineConfig({
  test: {
    browser: {
      name: 'chromium', 
      providerOptions: { 
        launch: { devtools: true }, 
      }, 
      instances: [ 
        { 
          browser: 'chromium', 
          launch: { devtools: true }, 
        }, 
      ], 
    },
  },
})

S novým polem browser.instances můžete také specifikovat více konfigurací prohlížeče.

spy.mockReset nyní obnovuje původní implementaci

Dříve neexistoval dobrý způsob, jak resetovat spy na původní implementaci, aniž by se musel znovu aplikovat. Nyní spy.mockReset resetuje implementační funkci na původní, namísto prázdné (noop) funkce.

const foo = {
  bar: () => 'Hello, world!',
};

vi.spyOn(foo, 'bar').mockImplementation(() => 'Hello, mock!');

foo.bar(); // 'Hello, mock!'

foo.bar.mockReset();

foo.bar(); // undefined
foo.bar(); // 'Hello, world!'

vi.spyOn znovu používá mock, pokud je metoda již mockována

Dříve Vitest vždy při špehování objektu přiřadil nový spy. To způsobovalo chyby s mockRestore, protože by obnovil spy na předchozí spy namísto původní funkce:

vi.spyOn(fooService, 'foo').mockImplementation(() => 'bar');
vi.spyOn(fooService, 'foo').mockImplementation(() => 'bar');
vi.restoreAllMocks();
vi.isMockFunction(fooService.foo); // true
vi.isMockFunction(fooService.foo); // false

Výchozí nastavení falešných časovačů

Vitest již neposkytuje výchozí možnosti fakeTimers.toFake. Nyní Vitest bude mockovat jakékoli API související s časovači, pokud je k dispozici (kromě nextTick). Konkrétně performance.now() je nyní mockováno, když je voláno vi.useFakeTimers().

vi.useFakeTimers();

performance.now(); // original
performance.now(); // fake

Můžete se vrátit k předchozímu chování tím, že při volání vi.useFakeTimers specifikujete časovače nebo je nastavíte globálně v konfiguraci:

export default defineConfig({
  test: {
    fakeTimers: {
      toFake: [ 
        'setTimeout', 
        'clearTimeout', 
        'setInterval', 
        'clearInterval', 
        'setImmediate', 
        'clearImmediate', 
        'Date', 
      ] 
    },
  },
})

Přísnější rovnost chyb

Vitest nyní kontroluje více vlastností při porovnávání chyb pomocí toEqual nebo toThrowError. Vitest nyní porovnává name, message, cause a AggregateError.errors. Pro Error.cause se porovnání provádí asymetricky:

expect(new Error('hi', { cause: 'x' })).toEqual(new Error('hi')); // ✅
expect(new Error('hi')).toEqual(new Error('hi', { cause: 'x' })); // ❌

Kromě kontroly více vlastností Vitest nyní porovnává prototypy chyb. Například, pokud byla vyhozena TypeError, kontrola rovnosti by se měla vztahovat na TypeError, nikoli na Error:

expect(() => {
  throw new TypeError('type error');
})
  .toThrowError(new Error('type error')) 
  .toThrowError(new TypeError('type error')); 

Více podrobností naleznete v PR: #5876.

Export podmínky module není ve Vite 6 ve výchozím nastavení vyřešen

Vite 6 umožňuje flexibilnější možnosti resolve.conditions a Vitest je konfiguruje tak, aby ve výchozím nastavení vylučovaly export s podmínkou module. Podrobnosti o změnách na straně Vite naleznete také v průvodci migrací Vite 6.

Typ Custom je zastaralý API

Typ Custom je nyní aliasem pro typ Test. Všimněte si, že Vitest aktualizoval veřejné typy ve verzi 2.1 a změnil exportované názvy na RunnerCustomCase a RunnerTestCase:

import {
  RunnerCustomCase, 
  RunnerTestCase, 
} from 'vitest';

Pokud používáte getCurrentSuite().custom(), type vrácené úlohy je nyní nastaveno na 'test'. Typ Custom bude odstraněn ve Vitest 4.

Typ WorkspaceSpec se již nepoužívá API

Ve veřejném API byl tento typ dříve používán v vlastních sekvencerech. Místo něj prosím migrujte na TestSpecification.

onTestFinished a onTestFailed nyní přijímají kontext

Hooky onTestFinished a onTestFailed dříve jako první argument přijímaly výsledek testu. Nyní přijímají kontext testu, stejně jako beforeEach a afterEach.

Změny v Snapshot API API

Veřejné Snapshot API v @vitest/snapshot bylo změněno tak, aby podporovalo více stavů v rámci jednoho spuštění. Více podrobností naleznete v PR: #6817

Všimněte si, že tyto změny ovlivňují pouze vývojáře, kteří přímo používají Snapshot API. V API .toMatchSnapshot nedošlo k žádným změnám.

Změny v signatuře typu resolveConfig API

Funkce resolveConfig je nyní užitečnější. Namísto přijímání již vyřešené konfigurace Vite nyní přijímá uživatelskou konfiguraci a vrací vyřešenou konfiguraci.

Tato funkce se interně nepoužívá a je vystavena výhradně jako veřejné API.

Vyčištěné typy vitest/reporters API

Vstupní bod vitest/reporters nyní exportuje pouze implementace reportérů a jejich typy možností. Pokud potřebujete přístup k TestCase/TestSuite a dalším typům souvisejícím s úkoly, importujte je navíc z vitest/node.

Pokrytí ignoruje testovací soubory, i když je coverage.excludes přepsáno.

Již není možné zahrnout testovací soubory do zprávy o pokrytí přepsáním nastavení coverage.excludes. Testovací soubory jsou nyní vždy vyloučeny.

Migrace na Vitest 2.0

Výchozí pool je forks

Vitest 2.0 mění výchozí konfiguraci pro pool na 'forks' pro lepší stabilitu. Celou motivaci si můžete přečíst v PR.

Pokud jste používali poolOptions bez určení pool, možná budete muset aktualizovat konfiguraci:

export default defineConfig({
  test: {
    poolOptions: {
      threads: { 
        singleThread: true, 
      }, 
      forks: { 
        singleFork: true, 
      }, 
    }
  }
})

Hooky se nyní provádějí sekvenčně

Před Vitest 2.0 běžely všechny hooky paralelně. Ve verzi 2.0 běží všechny hooky sériově. Navíc hooky afterAll/afterEach jsou spouštěny v opačném pořadí.

Pro návrat k paralelnímu provádění hooků změňte sequence.hooks na 'parallel':

export default defineConfig({
  test: {
    sequence: { 
      hooks: 'parallel', 
    }, 
  },
})

suite.concurrent spouští všechny testy souběžně

Dříve by specifikace concurrent na sadě seskupila souběžné testy podle sad a spouštěla je sekvenčně. Nyní, podle chování Jestu, se všechny testy spouštějí souběžně (s omezením maxConcurrency).

coverage.ignoreEmptyLines pro V8 Coverage je ve výchozím nastavení povoleno

Výchozí hodnota coverage.ignoreEmptyLines je nyní true. Tato významná změna může ovlivnit reporty pokrytí kódu a vyžadovat úpravy prahových hodnot pro pokrytí pro některé projekty. Tato úprava ovlivňuje pouze výchozí nastavení, když je coverage.provider 'v8'.

Odstranění možnosti watchExclude

Vitest používá watcher Vite. Vylučte soubory nebo adresáře přidáním do server.watch.ignored:

export default defineConfig({
  server: { 
    watch: { 
      ignored: ['!node_modules/examplejs'] 
    } 
  } 
})

--segfault-retry odstraněno

Se změnami ve výchozím fondu již tato možnost není potřeba. Pokud narazíte na chyby segfault, zkuste přepnout na fond 'forks'. Pokud problém přetrvává, otevřete prosím nový problém s reprodukcí.

Prázdná úloha v úlohách sady odstraněna

Toto je změna v pokročilém task API. Dříve by procházení .suite nakonec vedlo k prázdné interní sadě, která byla použita namísto úlohy souboru.

To činí .suite volitelným; pokud je úloha definována na nejvyšší úrovni, nebude mít sadu. Můžete se vrátit k vlastnosti .file, která je nyní přítomna u všech úloh (včetně samotné úlohy souboru, takže buďte opatrní, abyste nespadli do nekonečné rekurze).

Tato změna také odstraňuje soubor z expect.getState().currentTestName a činí expect.getState().testPath povinným.

task.meta je přidáno do JSON reportéru

JSON reportér nyní tiskne task.meta pro každý výsledek tvrzení.

Zjednodušené generické typy mockovacích funkcí (např. vi.fn<T>, Mock<T>)

Dříve vi.fn<TArgs, TReturn> přijímalo dva generické typy, odděleně pro argumenty a návratovou hodnotu. To je změněno tak, aby přímo přijímalo typ funkce vi.fn<T> pro zjednodušení použití.

import { vi } from 'vitest';
import type { Mock } from 'vitest';

const add = (x: number, y: number): number => x + y;

// using vi.fn<T>
const mockAdd = vi.fn<Parameters<typeof add>, ReturnType<typeof add>>(); 
const mockAdd = vi.fn<typeof add>(); 

// using Mock<T>
const mockAdd: Mock<Parameters<typeof add>, ReturnType<typeof add>> = vi.fn(); 
const mockAdd: Mock<typeof add> = vi.fn(); 

Přístup k vyřešeným mock.results

Dříve Vitest rozřešil hodnoty mock.results, pokud funkce vrátila Promise. Nyní existuje samostatná vlastnost mock.settledResults, která se naplní pouze tehdy, když je vrácená Promise rozřešena nebo zamítnuta.

const fn = vi.fn().mockResolvedValueOnce('result');
await fn();

const result = fn.mock.results[0]; // 'result'
const result = fn.mock.results[0]; // 'Promise<result>'

const settledResult = fn.mock.settledResults[0]; // 'result'

S touto změnou také zavádíme nové matchery toHaveResolved* podobné toHaveReturned, aby se usnadnila migrace, pokud jste dříve používali toHaveReturned:

const fn = vi.fn().mockResolvedValueOnce('result');
await fn();

expect(fn).toHaveReturned('result'); 
expect(fn).toHaveResolved('result'); 

Režim prohlížeče

Režim prohlížeče Vitest prošel během beta cyklu mnoha změnami. O naší filozofii režimu prohlížeče si můžete přečíst na diskuzní stránce GitHubu.

Většina změn byla aditivní, ale došlo k několika malým zásadním změnám:

• Poskytovatel none byl přejmenován na preview #5842
• Poskytovatel preview je nyní výchozí #5842
• indexScripts je přejmenováno na orchestratorScripts #5842

Odstraněné zastaralé možnosti

Některé zastaralé možnosti byly odstraněny:

• příkaz vitest typecheck – místo něj použijte vitest --typecheck
• proměnné prostředí VITEST_JUNIT_CLASSNAME a VITEST_JUNIT_SUITE_NAME (místo nich použijte možnosti reportéru)
• kontrola pokrytí c8 (místo ní použijte coverage-v8)
• export SnapshotEnvironment z vitest – importujte jej místo toho z vitest/snapshot
• SpyInstance je odstraněno ve prospěch MockInstance

Migrace na Vitest 1.0

Minimální požadavky

Vitest 1.0 vyžaduje Vite 5.0 a Node.js 18 nebo vyšší.

Všechny podbalíčky @vitest/* vyžadují Vitest verze 1.0.

Aktualizace snímků #3961

Uvozovky ve snímcích již nejsou escapovány a všechny snímky používají zpětné apostrofy (`) i v případě, že řetězec je pouze jeden řádek.

1. Uvozovky již nejsou escapovány:

expect({ foo: 'bar' }).toMatchInlineSnapshot(`
  Object {
-    \\"foo\\": \\"bar\\",
+    "foo": "bar",
  }
`)

2. Jednořádkové snímky nyní používají uvozovky "`" místo ':

- expect('some string').toMatchInlineSnapshot('"some string"')
+ expect('some string').toMatchInlineSnapshot(`"some string"`)

Došlo také ke změnám v balíčku @vitest/snapshot. Pokud jej nepoužíváte přímo, nemusíte nic měnit.

• Již nemusíte rozšiřovat SnapshotClient jen proto, abyste přepsali metodu equalityCheck: stačí ji předat jako isEqual při inicializaci instance
• client.setTest bylo přejmenováno na client.startCurrentRun
• client.resetCurrent bylo přejmenováno na client.finishCurrentRun

Fondy jsou standardizovány #4172

Odstranili jsme mnoho konfiguračních možností, abychom usnadnili konfiguraci spouštěče podle vašich potřeb. Podívejte se prosím na příklady migrace, pokud se spoléháte na --threads nebo jiné související parametry.

• --threads je nyní --pool=threads
• --no-threads je nyní --pool=forks
• --single-thread je nyní --poolOptions.threads.singleThread
• --experimental-vm-threads je nyní --pool=vmThreads
• --experimental-vm-worker-memory-limit je nyní --poolOptions.vmThreads.memoryLimit
• --isolate je nyní --poolOptions.<pool-name>.isolate a browser.isolate
• test.maxThreads je nyní test.poolOptions.<pool-name>.maxThreads
• test.minThreads je nyní test.poolOptions.<pool-name>.minThreads
• test.useAtomics je nyní test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process je nyní test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads je nyní test.poolMatchGlobs.vmThreads

{
  scripts: {
-    "test": "vitest --no-threads"
     // For identical behaviour:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // Or multi parallel forks:
+    "test": "vitest --pool forks"

  }
}

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

Změny v pokrytí #4265, #4442

Možnost coverage.all je nyní ve výchozím nastavení povolena. To znamená, že všechny soubory projektu odpovídající vzoru coverage.include budou zpracovány, i když nebudou spuštěny.

Tvar API pro prahové hodnoty pokrytí byl změněn a nyní podporuje specifikaci prahových hodnot pro konkrétní soubory pomocí glob vzorů:

export default defineConfig({
  test: {
    coverage: {
-      perFile: true,
-      thresholdAutoUpdate: true,
-      100: true,
-      lines: 100,
-      functions: 100,
-      branches: 100,
-      statements: 100,
+      thresholds: {
+        perFile: true,
+        autoUpdate: true,
+        100: true,
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      }
    }
  }
})

Mock typy #4400

Několik typů bylo odstraněno ve prospěch názvů "Mock" ve stylu Jestu.

- import { EnhancedSpy, SpyInstance } from 'vitest'
+ import { MockInstance } from 'vitest'

WARNING

SpyInstance je zastaralé ve prospěch MockInstance a bude odstraněno v další hlavní verzi.

Mocky časovačů #3925

vi.useFakeTimers() již automaticky nemockuje process.nextTick. Stále je možné mockovat process.nextTick explicitním zadáním pomocí vi.useFakeTimers({ toFake: ['nextTick'] }).

Nicméně, mockování process.nextTick není možné při použití --pool=forks. Pokud potřebujete mockování process.nextTick, použijte jinou možnost --pool.

Migrace z Jestu

Vitest byl navržen s API kompatibilním s Jestem, aby byla migrace z Jestu co nejjednodušší. Navzdory těmto snahám se stále můžete setkat s následujícími rozdíly:

Globální proměnné jako výchozí

Jest má své globální API ve výchozím nastavení povoleno. Vitest však nikoli. Můžete buď povolit globální proměnné pomocí nastavení konfigurace globals, nebo aktualizovat svůj kód tak, aby místo toho používal importy z modulu vitest.

Pokud se rozhodnete ponechat globální proměnné zakázané, mějte na paměti, že běžné knihovny, jako je testing-library, nebudou automaticky provádět čištění DOM.

spy.mockReset

Funkce mockReset v Jestu nahrazuje mock implementaci prázdnou funkcí, která vrací undefined.

Funkce mockReset ve Vitestu resetuje mock implementaci na její původní stav. To znamená, že resetování mocku vytvořeného pomocí vi.fn(impl) resetuje mock implementaci na impl.

Modulové mocky

Při mockování modulu v Jestu je návratová hodnota argumentu factory výchozím exportem. Ve Vitestu musí argument factory vrátit objekt s explicitně definovaným každým exportem. Například následující jest.mock by musel být aktualizován takto:

jest.mock('./some-path', () => 'hello') 
vi.mock('./some-path', () => ({ 
  default: 'hello', 
})) 

Pro více podrobností se prosím podívejte na sekci API vi.mock.

Chování automatického mockování

Na rozdíl od Jestu se mockované moduly v <root>/__mocks__ nenačítají, dokud není voláno vi.mock(). Pokud je potřebujete mockovat v každém testu, stejně jako v Jestu, můžete je mockovat uvnitř setupFiles.

Import originálu mockovaného balíčku

Pokud jste pouze částečně mockovali balíček, možná jste dříve používali funkci requireActual z Jestu. Ve Vitestu byste měli tyto volání nahradit vi.importActual.

const { cloneDeep } = jest.requireActual('lodash/cloneDeep'); 
const { cloneDeep } = await vi.importActual('lodash/cloneDeep'); 

Rozšíření mockování na externí knihovny

Zatímco Jest to dělá ve výchozím nastavení, při mockování modulu a snaze rozšířit toto mockování na další externí knihovny, které používají stejný modul, měli byste explicitně uvést, kterou knihovnu třetí strany chcete mockovat. Toho docílíte pomocí server.deps.inline, čímž se externí knihovna stane součástí vašeho zdrojového kódu.

server.deps.inline: ["lib-name"]

expect.getState().currentTestName

Názvy test ve Vitestu jsou spojeny symbolem > pro snazší rozlišení testů od sad, zatímco Jest používá prázdnou mezeru ().

- `${describeTitle} ${testTitle}`
+ `${describeTitle} > ${testTitle}`

Proměnné prostředí

Stejně jako Jest, Vitest nastaví NODE_ENV na test, pokud nebyl dříve nastaven. Vitest má také protějšek pro JEST_WORKER_ID, který se nazývá VITEST_POOL_ID (vždy menší nebo roven maxThreads), takže pokud se na něj spoléháte, nezapomeňte jej přejmenovat. Vitest také vystavuje VITEST_WORKER_ID, což je unikátní ID běžícího workeru – toto číslo není ovlivněno maxThreads a bude se zvyšovat s každým vytvořeným workerem.

Nahradit vlastnost

Pokud chcete upravit objekt, v Jestu použijete replaceProperty API. Ve Vitestu můžete k provedení stejného použít vi.stubEnv nebo vi.spyOn.

Done Callback

Od verze Vitest v0.10.0 je styl deklarace testů pomocí callbacků zastaralý. Můžete je přepsat tak, aby používaly async/await funkce, nebo použít Promise k napodobení stylu callbacků.

it('should work', (done) => {  
it('should work', () => new Promise(done => { 
  // ...
  done()
}) 
})) 

Hooky

Hooky beforeAll/beforeEach mohou ve Vitestu vracet teardown funkci (funkci pro úklid). Z tohoto důvodu možná budete muset přepsat deklarace vašich hooků, pokud vracejí něco jiného než undefined nebo null:

beforeEach(() => setActivePinia(createTestingPinia())) 
beforeEach(() => { setActivePinia(createTestingPinia()) }) 

V Jestu jsou hooky volány sekvenčně (jeden po druhém). Ve výchozím nastavení Vitest spouští hooky paralelně. Chcete-li použít chování Jestu, aktualizujte možnost sequence.hooks:

export default defineConfig({
  test: {
    sequence: { 
      hooks: 'list', 
    } 
  }
})

Typy

Vitest nemá ekvivalent k jmennému prostoru jest, takže budete muset importovat typy přímo z vitest:

let fn: jest.Mock<(name: string) => number>; 
import type { Mock } from 'vitest'; 
let fn: Mock<(name: string) => number>; 

Časovače

Vitest nepodporuje starší časovače Jestu.

Časový limit

Pokud jste používali jest.setTimeout, budete muset přejít na vi.setConfig:

jest.setTimeout(5_000); 
vi.setConfig({ testTimeout: 5_000 }); 

Vue snímky

Toto není funkce specifická pro Jest, ale pokud jste dříve používali Jest s předvolbou vue-cli, budete muset nainstalovat balíček jest-serializer-vue a použít jej uvnitř setupFiles:

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js'],
  },
});

tests/unit/setup.js

import vueSnapshotSerializer from 'jest-serializer-vue';

expect.addSnapshotSerializer(vueSnapshotSerializer);

Jinak budou vaše snímky obsahovat mnoho escapovaných znaků ".