Migrációs útmutató

Migrálás Vitest 3.0-ra

Teszt opciók harmadik argumentumként

A Vitest 3.0 figyelmeztetést ad, ha objektumot ad át harmadik argumentumként a test vagy describe függvényeknek:

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

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

A következő főverzió hibát fog dobni, ha a harmadik argumentum objektum. Megjegyzendő, hogy az időtúllépés száma nem elavult:

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

browser.name és browser.providerOptions elavultak

Mind a browser.name, mind a browser.providerOptions el lesz távolítva a Vitest 4-ben. Helyettük használja az új browser.instances opciót:

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

Az új browser.instances mezővel több böngészőkonfigurációt is megadhat.

spy.mockReset most visszaállítja az eredeti implementációt

Korábban nem volt jó módja a spy visszaállításának az eredeti implementációra anélkül, hogy újra alkalmaztuk volna. Most a spy.mockReset visszaállítja az implementációs függvényt az eredetire, nem pedig egy hamis noop-ra.

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 újra felhasználja a mockot, ha a metódus már mockolt

Korábban a Vitest mindig új spy-t rendelt hozzá, amikor egy objektumon spyOn-t hívott. Ez hibákat okozott a mockRestore esetén, mert az a spy-t az előző spy-ra állította vissza az eredeti függvény helyett:

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

Mock időzítők alapértelmezései

A Vitest már nem nyújt alapértelmezett fakeTimers.toFake opciókat. Mostantól a Vitest minden időzítővel kapcsolatos API-t mockol, ha elérhető (kivéve a nextTick-et). Például, a performance.now() mostantól mockolt, amikor a vi.useFakeTimers meghívásra kerül.

vi.useFakeTimers();

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

Visszaállíthatja a korábbi működést az időzítők explicit megadásával a vi.useFakeTimers hívásakor, vagy globálisan a konfigurációban:

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

Szigorúbb hibaösszehasonlítás

A Vitest mostantól több tulajdonságot ellenőriz, amikor hibákat hasonlít össze a toEqual vagy toThrowError használatával. A Vitest most összehasonlítja a name, message, cause és AggregateError.errors tulajdonságokat. Az Error.cause esetében az összehasonlítás aszimmetrikusan történik:

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

A tulajdonságok ellenőrzésén túl a Vitest most összehasonlítja a hiba prototípusokat is. Például, ha TypeError dobásra került, az egyenlőségi ellenőrzésnek TypeError-re kell hivatkoznia, nem Error-ra:

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

További részletekért lásd a PR-t: #5876.

A module feltételes export alapértelmezés szerint nem oldódik fel a Vite 6-ban

A Vite 6 rugalmasabb resolve.conditions opciókat tesz lehetővé, és a Vitest alapértelmezés szerint kizárja a module feltételes exportot. Lásd még a Vite 6 migrációs útmutatót a Vite oldali változások részleteiért.

A Custom típus elavult API

A Custom típus mostantól a Test típus aliasa. Megjegyzendő, hogy a Vitest frissítette a nyilvános típusokat a 2.1-ben, és az exportált neveket RunnerCustomCase-re és RunnerTestCase-re változtatta:

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

Ha a getCurrentSuite().custom()-t használja, a visszaadott feladat type értéke mostantól 'test'. A Custom típus el lesz távolítva a Vitest 4-ben.

A WorkspaceSpec típus már nem használatos API

A nyilvános API-ban ezt a típust korábban egyéni sorrendezőkben használták. Kérjük, migráljon a TestSpecification típusra.

onTestFinished és onTestFailed mostantól kontextust kapnak

Az onTestFinished és onTestFailed hookok korábban teszteredményt kaptak első argumentumként. Mostantól tesztkontextust kapnak, mint a beforeEach és afterEach.

Változások a Snapshot API-ban API

A @vitest/snapshot nyilvános Snapshot API-ja megváltozott, hogy támogassa a több állapotot egyetlen futtatáson belül. További részletekért lásd a PR-t: #6817

Megjegyzendő, hogy ezek a változások csak azokat a fejlesztőket érintik, akik közvetlenül használják a Snapshot API-t. A .toMatchSnapshot API-ban nem történt változás.

Változások a resolveConfig típus aláírásában API

A resolveConfig mostantól hasznosabb. Ahelyett, hogy már feloldott Vite konfigurációt fogadna, mostantól felhasználói konfigurációt fogad el, és feloldott konfigurációt ad vissza.

Ez a függvény belsőleg nem használatos, és kizárólag nyilvános API-ként van közzétéve.

Tisztított vitest/reporters típusok API

A vitest/reporters modul mostantól csak a riporter implementációkat és opciótípusokat exportálja. Ha hozzáférésre van szüksége a TestCase/TestSuite és más feladattal kapcsolatos típusokhoz, importálja azokat emellett a vitest/node modulból.

A lefedettség figyelmen kívül hagyja a tesztfájlokat, még akkor is, ha a coverage.excludes felülíródik.

Már nem lehetséges tesztfájlokat felvenni a lefedettségi jelentésbe a coverage.excludes felülírásával. A tesztfájlok mostantól mindig ki vannak zárva.

Migrálás Vitest 2.0-ra

Az alapértelmezett pool forks

A Vitest 2.0 a pool alapértelmezett konfigurációját 'forks'-ra változtatja a jobb stabilitás érdekében. A teljes motivációt elolvashatja a PR-ben.

Ha poolOptions-t használt anélkül, hogy pool-t megadott volna, előfordulhat, hogy frissítenie kell a konfigurációt:

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

A hookok stackben futnak

A Vitest 2.0 előtt minden hook párhuzamosan futott. A 2.0-ban azonban minden hook sorosan fut. Ezenkívül az afterAll/afterEach hookok fordított sorrendben futnak.

A hookok párhuzamos végrehajtására való visszatéréshez módosítsa a sequence.hooks értékét 'parallel'-re:

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

suite.concurrent az összes tesztet párhuzamosan futtatja

Korábban a concurrent megadása egy tesztsorozaton belül csoportosította a párhuzamos teszteket, sorosan futtatva őket. Mostantól, a Jest viselkedését követve, minden teszt párhuzamosan fut (a maxConcurrency korlátok figyelembevételével).

A V8 Coverage coverage.ignoreEmptyLines alapértelmezés szerint engedélyezve van

A coverage.ignoreEmptyLines alapértelmezett értéke mostantól true. Ez a jelentős változás befolyásolhatja a kódlefedettségi jelentéseket, és egyes projektek esetében szükségessé teheti a lefedettségi küszöbök módosítását. Ez a módosítás csak az alapértelmezett beállítást érinti, amikor a coverage.provider értéke 'v8'.

A watchExclude opció eltávolítása

A Vitest a Vite figyelőjét használja. Zárja ki a fájlokat vagy könyvtárakat a server.watch.ignored hozzáadásával:

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

--segfault-retry eltávolítva

A pool alapértelmezett beállításainak változásával ez az opció már nem szükséges. Ha szegmentálási hibákat tapasztal, próbálja meg átváltani a 'forks' poolra. Ha a probléma továbbra is fennáll, kérjük, nyisson egy új hibajegyet reprodukcióval.

Üres feladat a tesztsorozat feladataiban eltávolítva

Ez a változás a fejlett feladat API-ra vonatkozik. Korábban a .suite bejárása végül az üres belső tesztsorozatot eredményezte, amelyet fájlfeladat helyett használtak.

Ez opcionálissá teszi a .suite-t; ha a feladat a legfelső szinten van definiálva, akkor nem lesz hozzárendelt tesztsorozata. Visszaállhat a .file tulajdonságra, amely mostantól minden feladaton (beleértve magát a fájlfeladatot is) elérhető, ezért ügyeljen arra, hogy ne essen végtelen rekurzióba.

Ez a változás eltávolítja a fájlt az expect.getState().currentTestName mezőből, és kötelezővé teszi az expect.getState().testPath mező meglétét.

task.meta hozzáadva a JSON riporterhez

A JSON riporter mostantól minden állítási eredményhez kiírja a task.meta mezőt.

Egyszerűsített általános típusok a mock függvényekhez (pl. vi.fn<T>, Mock<T>)

Korábban a vi.fn<TArgs, TReturn> két általános típust fogadott el külön az argumentumokhoz és a visszatérési értékhez. Ez megváltozott, hogy közvetlenül egy függvénytípust fogadjon vi.fn<T> a használat egyszerűsítése érdekében.

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(); 

Feloldott mock.results elérése

Korábban a Vitest feloldotta a mock.results értékeket, ha a függvény Promise-t adott vissza. Mostantól van egy külön mock.settledResults tulajdonság, amely csak akkor populálódik, ha a visszaadott Promise feloldódik vagy elutasításra kerül.

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'

Ezzel a változással új toHaveResolved* illesztőket is bevezetünk, hasonlóan a toHaveReturned-hez, hogy megkönnyítsük a migrációt, ha korábban a toHaveReturned-t használta:

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

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

Böngésző mód

A Vitest böngésző módja sok változáson esett át a béta ciklus során. A böngésző mód filozófiájáról a GitHub vitafórumon olvashat.

A legtöbb változás additív volt, de volt néhány kisebb törést okozó változás:

• A none szolgáltatót átnevezték preview-ra #5842
• A preview szolgáltató mostantól alapértelmezett #5842
• Az indexScripts átnevezésre került orchestratorScripts-re #5842

Elavult opciók eltávolítva

Néhány elavult opciót eltávolítottak:

• vitest typecheck parancs - helyette használja a vitest --typecheck parancsot
• VITEST_JUNIT_CLASSNAME és VITEST_JUNIT_SUITE_NAME környezeti változók (helyette használja a riporter opciókat)
• c8 lefedettség ellenőrzése (helyette használja a coverage-v8-at)
• SnapshotEnvironment exportálása a vitest-ből - helyette importálja a vitest/snapshot modulból
• SpyInstance eltávolítva a MockInstance javára

Migrálás Vitest 1.0-ra

Minimális követelmények

A Vitest 1.0-hoz Vite 5.0 és Node.js 18 vagy újabb verzió szükséges.

Minden @vitest/* alcsomaghoz Vitest 1.0-s verzió szükséges.

Snapshots frissítése #3961

A snapshotokban lévő idézőjelek már nincsenek escape-elve, és minden snapshot backtick-eket (`) használ, még akkor is, ha a string csak egyetlen sor.

1. Az idézőjelek már nincsenek escape-elve:

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

2. Az egysoros snapshotok mostantól "`" idézőjeleket használnak a ':' helyett:

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

Változások történtek a @vitest/snapshot csomagban is (#4076). Ha nem használja közvetlenül, akkor nem kell semmit sem változtatnia.

• Már nem kell kiterjesztenie a SnapshotClient-et csak az equalityCheck metódus felülírásához: egyszerűen adja át isEqual néven az inicializáláskor
• A client.setTest átnevezésre került client.startCurrentRun-ra
• A client.resetCurrent átnevezésre került client.finishCurrentRun-ra

A poolok szabványosítva vannak #4172

Sok konfigurációs opciót eltávolítottunk, hogy könnyebbé tegyük a tesztfuttató konfigurálását az Ön igényeinek megfelelően. Kérjük, tekintse meg a migrációs példákat, ha a --threads vagy más kapcsolódó jelzőket használja.

• --threads mostantól --pool=threads
• --no-threads mostantól --pool=forks
• --single-thread mostantól --poolOptions.threads.singleThread
• --experimental-vm-threads mostantól --pool=vmThreads
• --experimental-vm-worker-memory-limit mostantól --poolOptions.vmThreads.memoryLimit
• --isolate mostantól --poolOptions.<pool-name>.isolate és browser.isolate
• test.maxThreads mostantól test.poolOptions.<pool-name>.maxThreads
• test.minThreads mostantól test.poolOptions.<pool-name>.minThreads
• test.useAtomics mostantól test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process mostantól test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads mostantól test.poolMatchGlobs.vmThreads

{
  scripts: {
-    "test": "vitest --no-threads"
     // Azonos viselkedéshez:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // Vagy több párhuzamos fork:
+    "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"
  }
}

Változások a lefedettségben #4265, #4442

A coverage.all opció mostantól alapértelmezés szerint engedélyezve van. Ez azt jelenti, hogy minden projektfájl, amely megfelel a coverage.include mintának, feldolgozásra kerül, még akkor is, ha nem hajtódik végre.

A lefedettségi küszöbök API-jának alakja megváltozott, és mostantól támogatja a küszöbök megadását specifikus fájlokhoz glob minták használatával:

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 típusok #4400

Néhány típust eltávolítottak a Jest-stílusú "Mock" elnevezés mellett.

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

WARNING

A SpyInstance elavult a MockInstance javára, és a következő főverzióban eltávolításra kerül.

Időzítő mockok #3925

A vi.useFakeTimers() már nem mockolja automatikusan a process.nextTick függvényt. A process.nextTick továbbra is mockolható, ha explicit módon megadja a vi.useFakeTimers({ toFake: ['nextTick'] }) használatával.

Azonban a process.nextTick nem mockolható, ha a --pool=forks opciót használja. Használjon másik --pool opciót, ha szüksége van a process.nextTick mockolására.

Migrálás Jest-ről

A Vitest-et Jest-kompatibilis API-val tervezték, hogy a Jest-ről való migráció a lehető legegyszerűbb legyen. Ezen erőfeszítések ellenére is találkozhat a következő különbségekkel:

Globális változók alapértelmezettként

A Jest globális API-ja alapértelmezés szerint engedélyezve van. A Vitest esetében ez nem így van. Engedélyezheti a globális változókat a globals konfigurációs beállításon keresztül, vagy frissítheti a kódját, hogy a vitest modulból importálja a szükséges funkciókat.

Ha úgy dönt, hogy a globális változókat letiltva tartja, vegye figyelembe, hogy az olyan gyakori könyvtárak, mint a testing-library, nem fogják automatikusan elvégezni a DOM tisztítását.

spy.mockReset

A Jest mockReset egy üres függvénnyel helyettesíti a mock implementációt, amely undefined értéket ad vissza.

A Vitest mockReset visszaállítja a mock implementációt az eredetire. Ez azt jelenti, hogy egy vi.fn(impl) által létrehozott mock visszaállítása az impl mock implementációra állítja vissza.

Modul mockok

Amikor egy modult mockol a Jestben, a factory argumentum visszatérési értéke az alapértelmezett export. A Vitestben a factory argumentumnak egy objektumot kell visszaadnia, amelyben minden export explicit módon definiálva van. Például a következő jest.mock frissítésre szorulna a következőképpen:

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

További részletekért lásd a vi.mock API szekciót.

Automatikus mockolási viselkedés

A Jesttel ellentétben a <root>/__mocks__ mappában lévő mockolt modulok nem töltődnek be, hacsak nem hívják meg a vi.mock() függvényt. Ha azt szeretné, hogy minden tesztben mockolva legyenek, mint a Jestben, akkor mockolhatja őket a setupFiles fájlokban.

Az eredeti mockolt csomag importálása

Ha csak részlegesen mockol egy csomagot, korábban valószínűleg a Jest requireActual függvényét használta. A Vitestben ezeket a hívásokat a vi.importActual függvényre kell cserélnie.

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

Mockolás kiterjesztése külső könyvtárakra

Míg a Jest alapértelmezés szerint kiterjeszti a mockolást, Vitestben egy modul mockolásakor, ha azt szeretné, hogy ez a mockolás más külső könyvtárakra is kiterjedjen, amelyek ugyanazt a modult használják, explicit módon meg kell adnia, melyik harmadik féltől származó könyvtárat szeretné mockolni. Ehhez a server.deps.inline opciót kell használnia, így a külső könyvtár a forráskódjának részévé válik.

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

expect.getState().currentTestName

A Vitest test nevei > szimbólummal vannak összekapcsolva, hogy könnyebben megkülönböztethetők legyenek a tesztek a tesztcsomagoktól, míg a Jest üres szóközt () használ.

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

Környezeti változók

A Jesthez hasonlóan a Vitest is test értékre állítja a NODE_ENV környezeti változót, amennyiben korábban nem volt beállítva. A Vitestnek van egy megfelelője a JEST_WORKER_ID számára, a VITEST_POOL_ID (mindig kisebb vagy egyenlő, mint a maxThreads), így ha erre támaszkodik, ne felejtse el átnevezni. A Vitest emellett elérhetővé teszi a VITEST_WORKER_ID változót is, amely egy futó worker egyedi azonosítója – ezt a számot nem befolyásolja a maxThreads, és minden létrehozott workerrel növekedni fog.

Tulajdonság cseréje

Ha módosítani szeretné az objektumot, a Jestben a replaceProperty API-t fogja használni. A Vitestben ugyanezt a vi.stubEnv vagy a vi.spyOn segítségével teheti meg.

Kész visszahívás

A Vitest v0.10.0-tól kezdve a tesztek deklarálásának callback stílusa elavult. Átírhatja őket async/await függvényekre, vagy használhat Promise-t a visszahívásos stílus imitálására.

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

Hookok

A beforeAll/beforeEach hookok teardown függvényt adhatnak vissza a Vitestben. Emiatt előfordulhat, hogy át kell írnia a hook deklarációit, ha azok nem undefined vagy null értékkel térnek vissza:

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

A Jestben a hookok sorosan (egymás után) hívódnak meg. Alapértelmezés szerint a Vitest párhuzamosan futtatja a hookokat. A Jest viselkedésének használatához frissítse a sequence.hooks opciót:

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

Típusok

A Vitestnek nincs megfelelője a jest névtérnek, ezért a típusokat közvetlenül a vitest modulból kell importálnia:

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

Időzítők

A Vitest nem támogatja a Jest régi időzítőit.

Időtúllépés

Ha a jest.setTimeout függvényt használta, át kell térnie a vi.setConfig függvényre:

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

Vue snapshotok

Ez nem Jest-specifikus funkció, de ha korábban Jestet használt vue-cli presettel, akkor telepítenie kell a jest-serializer-vue csomagot, és használnia kell a setupFiles fájlokban:

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);

Ellenkező esetben a snapshotjai sok escape-elt " karaktert fognak tartalmazni.