MARS TECH vite-debug-plugin

Tests (Vitest / Jest)

$debug est installé par l'environnement d'exécution du plugin : injection dans le navigateur, import virtuel SSR, globale du serveur de développement. Un lanceur de tests unitaires n'exécute rien de tout cela : le code source qui appelle $debug(...), surtout au moment de l'évaluation du module, lève ReferenceError: $debug is not defined. Un bouchon inerte (une fonction vide) corrige le problème : il se comporte exactement comme un build de production dont les appels ont été supprimés.

Vitest : automatique (rien à ajouter)

Si mtDebug() figure dans la config Vite que lit Vitest (le cas courant : Vitest fusionne votre vite.config), le plugin détecte l'exécution des tests et enregistre le bouchon pour vous en tête de setupFiles. Lancez vos tests : $debug est défini. Désactivez ce comportement avec mtDebug({ test: false }).

Fonctionnement

Il ne s'agit pas d'un hook de plugin Vite ou Vitest à ajouter : le plugin que vous avez déjà fournit un fichier de configuration des tests, une globale installée avant que vos tests n'importent quoi que ce soit. L'enregistrement automatique du bouchon inerte ne couvre que le $debug par défaut. Pour un globalName personnalisé, mettez test: false et enregistrez le bouchon vous-même, voir Bouchon programmatique. Avec test: 'log', cette limite ne s'applique pas : le plugin génère le module de configuration des tests à partir de votre configuration résolue, donc une globale personnalisée y fonctionne sans configuration supplémentaire.

L'option test remplace testStub et testLog de la 0.6. Les deux fonctionnent encore, avec un avertissement, jusqu'à la 2.0 : voir Options renommées.

Explicite : Jest, ou une config Vitest sans le plugin

Ajoutez le module de configuration des tests fourni à setupFiles, en premier, avant tout autre fichier de configuration des tests qui importe votre code source :

ts
// vitest.config.ts (ou config jest)
export default defineConfig({
  test: {
    setupFiles: ["@mars-tech/vite-debug-plugin/testing"],
  },
});

L'import installe un $debug inerte : la fonction appelable plus toute la surface de MTDebug, soit les 14 méthodes.

Bouchon manuel (sans dépendance)

Si vous préférez ne pas importer le paquet dans les tests, écrivez le bouchon à la main. Il doit être la première entrée de setupFiles et ne contenir aucun import. Les modules ES évaluent les imports d'un fichier avant son corps : un bouchon placé après des imports (ou dans un fichier qui importe indirectement des modules utilisant $debug) s'exécute trop tard, et l'erreur est quand même levée :

js
// tests/debug-stub.js   (setupFiles: ["./tests/debug-stub.js", ...])  — AUCUN import
const noop = () => {};
globalThis.$debug = Object.assign(noop, {
  ns: () => noop,
  enable: noop,
  disable: noop,
  setLevel: noop,
  setPrefixFilter: noop,
  assert: noop,
  time: noop,
  timeEnd: noop,
  count: noop,
  group: noop,
  groupCollapsed: noop,
  groupEnd: noop,
  table: noop,
  dir: noop,
});

Voir la sortie de $debug dans les tests

Le bouchon est inerte : il empêche les tests de planter, mais avale la sortie. Pour voir les logs pendant l'exécution des tests, depuis vos fichiers de test et depuis les composants ou le code de bibliothèque qu'ils exercent, réglez une seule option :

ts
// vite.config.ts
mtDebug({ test: "log" });

Sous Vitest, le plugin remplace le bouchon par un vrai $debug console formaté. Il tient compte de la configuration : le plugin génère son module de configuration des tests à partir de vos prefix, globalName, levels, prefixFilter et redact / redactDefaults résolus, donc la sortie des tests correspond à celle du développement et elle est masquée de la même façon, logs de CI compris. Chaque projet Vitest a son propre module : les projets ne partagent jamais leurs réglages. Le journaliseur inclut les valeurs multiples et la substitution printf ainsi que le rendu des charges utiles des environnements d'exécution navigateur et SSR : c'est le même code. Rien d'autre à ajouter. Avec enabled: false, test: 'log' se replie sur le bouchon inerte.

Filtrez avec les mêmes variables d'environnement que l'environnement d'exécution :

bash
MT_DEBUG=cart* MT_DEBUG_LEVEL=info vitest

Une ligne écrite par une bibliothèque construite avec brandPrefix garde son propre préfixe, donc les logs de l'application et ceux de la bibliothèque restent distinguables pendant les tests :

text
XYZ Info [A/UsesB] - UsesB mounted        ← votre app (préfixe XYZ)
ABC Info [cart/action] - cart.add(…)      ← bibliothèque B (préfixe ABC)

Simulez la bibliothèque (vi.mock('…')) et ses lignes cessent simplement d'apparaître : seuls les logs de votre application restent. Voir Marquer les logs de bibliothèque avec brandPrefix.

Sortie en ligne

Par défaut, Vitest regroupe la sortie console sous chaque test. Passez --disableConsoleIntercept (ou --reporter=verbose) pour voir les lignes au fil de l'exécution.

Appeler $debug dans les fichiers de test ne demande aucun changement d'environnement d'exécution : le bouchon ou le journaliseur le définit. Pour l'éditeur et la CI, TypeScript récupère la globale depuis le /// <reference types="@mars-tech/vite-debug-plugin/client" /> déjà ajouté (tant que vos fichiers de test font partie d'un tsconfig qui l'inclut, voir Activer le typage de la globale), et la configuration plate /eslint fournie déclare $debug, ce qui fait taire no-undef (voir Déclarer la globale à ESLint).

Entrées chaîne de redact dans les tests

Le module de configuration des tests généré contient vos entrées RegExp et les motifs de redactDefaults, jamais vos entrées chaîne : le texte d'un module peut finir dans les fichiers temporaires et le cache de modules de Vitest. Le journaliseur lit plutôt les entrées chaîne dans le processus qui charge votre configuration. Elles atteignent :

  • les workers threads et vmThreads, avec toute version de Vitest ;
  • les workers forks et vmForks à partir de Vitest 4, auxquels le plugin les fournit par le mécanisme provide / inject de Vitest.

Là où elles n'arrivent pas, le journaliseur n'affiche pas ce qu'il ne peut pas masquer : $debug n'affiche rien et le signale une fois. C'est le cas pour :

  • forks et vmForks sous Vitest 3. Mettez Vitest à jour, utilisez pool: "threads", ou décrivez chacune de ces valeurs par une RegExp de sa forme.
  • Un projet qui s'exécute dans un navigateur (mode navigateur de Vitest, --browser compris). Vitest recopie la console de la page de test dans son terminal, et les entrées chaîne ne sont jamais envoyées à un navigateur : avec des entrées chaîne configurées, le $debug de ce projet n'affiche rien et le plugin avertit. Avec seulement des entrées RegExp et redactDefaults, il écrit ses logs, masqués par celles-ci, et ne transmet aucune valeur vivante à la console. Pour y voir la sortie, remplacez chaque entrée chaîne par une RegExp de la forme de la valeur.

Quand plusieurs projets tournent dans un même processus, un journaliseur qui lit les règles des autres projets les applique aussi, en plus des siennes : les entrées chaîne d'un projet peuvent donc masquer aussi la sortie d'un autre. Voir Là où les entrées chaîne n'arrivent pas.

Un journaliseur dans votre propre fichier de configuration des tests

Sans le plugin (Jest, ou une config Vitest qui ne le charge pas), installez le journaliseur depuis votre propre premier fichier de configuration des tests. redact et redactDefaults prennent les mêmes valeurs que les options du plugin :

ts
// tests/setup.ts   (setupFiles: ["./tests/setup.ts"])
import { installMtDebugConsole } from "@mars-tech/vite-debug-plugin/testing";

installMtDebugConsole({
  prefix: "APP",
  redactDefaults: true,
  redact: [/sk_live_[A-Za-z0-9]+/],
});

Avec le plugin et test: 'log', n'ajoutez pas aussi @mars-tech/vite-debug-plugin/testing/log à setupFiles : le module généré installe déjà le journaliseur configuré. Votre propre fichier de configuration des tests s'exécute après lui. S'il importe /testing/log, le journaliseur configuré reste en place ; s'il appelle installMtDebugConsole(…), le nouveau journaliseur prend ses options et masque toujours avec les redact / redactDefaults de votre projet, en premier. Aucun des deux ne peut désactiver le masquage de votre projet.

Un journaliseur que vous installez vous-même avec test: 'stub' ou test: false lit les entrées chaîne de votre projet de la même façon, et n'affiche rien là où il ne les trouve pas. Un workerthreads les a toujours ; avec les pools forks, utilisez plutôt test: 'log' (Vitest 4) ou pool: "threads".

Bouchon programmatique : nom de globale personnalisé ou espions

Utilisez la forme programmatique depuis votre propre fichier de configuration des tests :

ts
// tests/setup.ts   (setupFiles: ["./tests/setup.ts"])
import { installMtDebugStub } from "@mars-tech/vite-debug-plugin/testing";
import { vi } from "vitest";

installMtDebugStub({ globalName: "$log", impl: vi.fn() }); // espionne chaque appel

globalName doit correspondre à l'option globalName du plugin (par défaut "$debug"). impl reçoit chaque appel de base $debug(...), y compris les appels passés par un journaliseur renvoyé par ns() ; par défaut, c'est une fonction inerte. Les méthodes utilitaires (time, count, group…) restent inertes. Le même module exporte aussi installMtDebugConsole, le journaliseur console qui tient compte de la configuration, présenté dans Un journaliseur dans votre propre fichier de configuration des tests. Voir Exports par sous-chemins.