Esecuzione dei Test

WARNING

Questa guida illustra l'utilizzo dell'API avanzata per eseguire i test tramite uno script Node.js. Se l'obiettivo è semplicemente eseguire i test, probabilmente non è necessaria. È destinata principalmente agli autori di librerie.

Le modifiche che introducono interruzioni potrebbero non seguire SemVer; si consiglia di bloccare la versione di Vitest quando si utilizza l'API sperimentale.

Vitest espone due metodi per avviare un'istanza di Vitest:

• startVitest avvia Vitest, verifica l'installazione dei pacchetti ed esegue immediatamente i test.
• createVitest avvia solo Vitest e non esegue alcun test.

startVitest

import { startVitest } from 'vitest/node';

const vitest = await startVitest(
  'test',
  [], // Filtri CLI
  {}, // Sovrascrivi la configurazione dei test
  {}, // Sovrascrivi la configurazione di Vite
  {} // Opzioni Vitest personalizzate
);
const testModules = vitest.state.getTestModules();
for (const testModule of testModules) {
  console.log(testModule.moduleId, testModule.ok() ? 'passato' : 'fallito');
}

TIP

Le API TestModule, TestSuite e TestCase non sono sperimentali e seguono SemVer a partire da Vitest 2.1.

createVitest

Crea un'istanza di Vitest senza eseguire i test.

Il metodo createVitest non verifica che i pacchetti richiesti siano installati. Inoltre, non tiene conto di config.standalone o config.mergeReports. Vitest non si chiuderà automaticamente anche se watch è disabilitato.

import { createVitest } from 'vitest/node';

const vitest = await createVitest(
  'test',
  {}, // Sovrascrivi la configurazione dei test
  {}, // Sovrascrivi la configurazione di Vite
  {} // Opzioni Vitest personalizzate
);

// chiamato quando viene invocato `vitest.cancelCurrentRun()`
vitest.onCancel(() => {});
// chiamato durante la chiamata `vitest.close()`
vitest.onClose(() => {});
// chiamato quando Vitest riesegue i file di test
vitest.onTestsRerun(files => {});

try {
  // questo imposterà process.exitCode a 1 se i test sono falliti,
  // e non chiuderà automaticamente il processo
  await vitest.start(['my-filter']);
} catch (err) {
  // questo può generare:
  // "FilesNotFoundError" se non sono stati trovati file
  // "GitNotFoundError" con `--changed` e il repository non è inizializzato
} finally {
  await vitest.close();
}

Se si intende mantenere l'istanza di Vitest attiva, assicurarsi di chiamare almeno init. Questo inizializzerà i reporter e il provider di copertura, ma non eseguirà alcun test. Si raccomanda inoltre di abilitare la modalità watch anche se non si intende utilizzare il watcher di Vitest, ma si desidera mantenere l'istanza in esecuzione. Vitest si basa su questo flag per il corretto funzionamento di alcune delle sue funzionalità in un processo continuo.

Dopo che i reporter sono stati inizializzati, utilizzare runTestSpecifications o rerunTestSpecifications per eseguire i test in caso di esecuzione manuale:

watcher.on('change', async file => {
  const specifications = vitest.getModuleSpecifications(file);
  if (specifications.length) {
    vitest.invalidateFile(file);
    // è possibile usare runTestSpecifications se gli hook "reporter.onWatcher*"
    // non devono essere chiamati
    await vitest.rerunTestSpecifications(specifications);
  }
});

WARNING

L'esempio sopra mostra un potenziale caso d'uso se si disabilita il comportamento predefinito del watcher. Per impostazione predefinita, Vitest riesegue già i test se i file cambiano.

Si noti inoltre che getModuleSpecifications non risolverà i file di test a meno che non siano già stati elaborati da globTestSpecifications. Se il file è stato appena creato, utilizzare project.matchesGlobPattern invece:

watcher.on('add', async file => {
  const specifications = [];
  for (const project of vitest.projects) {
    if (project.matchesGlobPattern(file)) {
      specifications.push(project.createSpecification(file));
    }
  }

  if (specifications.length) {
    await vitest.rerunTestSpecifications(specifications);
  }
});

Nei casi in cui è necessario disabilitare il watcher, è possibile configurare server.watch: null a partire da Vite 5.3 o server.watch: { ignored: ['*/*'] } in una configurazione di Vite:

await createVitest(
  'test',
  {},
  {
    plugins: [
      {
        name: 'stop-watcher',
        async configureServer(server) {
          await server.watcher.close();
        },
      },
    ],
    server: {
      watch: null,
    },
  }
);