Tests (Vitest / Jest)

$debug est installé par l'environnement d'exécution du plugin (injection navigateur, import virtuel SSR, globale du serveur de développement). Un exécuteur 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 sans effet corrige le problème : il se comporte exactement comme un build de production où les appels sont retirés.

Vitest — automatique (rien à ajouter)

Si mtDebug() figure dans la config Vite lue par 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({ testStub: false }).

Remarque

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 de test (une globale installée avant que vos tests n'importent quoi que ce soit). L'enregistrement automatique couvre le $debug par défaut ; pour un globalName personnalisé, mettez testStub: false et enregistrez le bouchon vous-même.

Explicite — Jest, ou une config Vitest sans le plugin

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

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

L'import installe un $debug sans effet (appelable, avec ns, enable, disable, setLevel, assert, time, timeEnd, count, group et groupEnd).

En 0.6, ce bouchon, comme celui qu'installe installMtDebugStub, n'a pas de setPrefixFilter : un code qui l'appelle lève une TypeError sous test. Utilisez le bouchon manuel ci-dessous, qui l'ajoute.

globalName personnalisé, ou pour vérifier les appels

Utilisez la forme programmatique depuis votre propre fichier de configuration :

// 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

installMtDebugStub accepte deux options : globalName (l'identifiant à installer, "$debug" par défaut ; reprenez le globalName du plugin) et impl (la fonction appelée à chaque appel, une fonction vide par défaut ; passez vi.fn() ou jest.fn() pour vérifier les appels). La fonction renvoie le bouchon installé.

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 le premier setupFile 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ève quand même l'erreur :

// 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,
  groupEnd: noop,
});

Voir la sortie $debug dans les tests

Le bouchon est sans effet : il empêche les tests d'échouer, 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, activez une option :

// vite.config.ts
mtDebug({ testLog: true });

Sous Vitest, le plugin remplace la fonction vide par un vrai $debug formaté, qui écrit dans la console. Il tient compte de la configuration : il utilise vos prefix, globalName et levels résolus (transmis au fichier de configuration des tests par l'environnement), si bien que le préfixe, le nom de la globale et le jeu de niveaux correspondent à ceux du développement. Rien d'autre à ajouter. testLog nécessite que testStub reste actif.

Sortie des tests en 0.6

En 0.6, le journaliseur des tests n'applique ni redact ni redactDefaults, utilise les libellés et les couleurs de niveau par défaut, et n'affiche ni emplacement source ni pile d'appels. Les valeurs masquées en développement apparaissent en clair dans la sortie des tests et dans les journaux de CI.

Filtrez avec les mêmes variables d'environnement que le filtre à l'exécution : MT_DEBUG=cart* MT_DEBUG_LEVEL=info vitest.

Une ligne émise par une bibliothèque construite avec libraryPrefix garde son préfixe : les logs de l'application et ceux de la bibliothèque restent distincts sous test :

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

Remplacez la bibliothèque par un mock (vi.mock('…')) et ses lignes cessent d'apparaître : seuls les logs de votre application restent.

Astuce

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 à l'exécution : le bouchon ou le journaliseur le définit. Côté éditeur et 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), et la config plate /eslint livrée déclare $debug, si bien que no-undef reste silencieux (voir Utilisation).