How to Enable Globals Mode

Docs for Vitest SDK v0.3.3

This guide shows you how to configure globals mode so your spec files need zero imports. By the end, you'll have ultra-clean spec files that read like plain-English documentation.

Prerequisites

• Node.js 18+
• A Vitest project with @swedevtools/livedoc-vitest installed
• Familiarity with explicit imports setup

Overview

Globals mode registers all LiveDoc keywords (feature, scenario, given, when, then, etc.) on globalThis via a setup file. Your spec files contain zero import statements — just pure Gherkin. The ESM thenable issue does not apply to globalThis properties, so then works as lowercase directly.

Step 1: Configure the Setup File

Add the LiveDoc setup file to your Vitest configuration. This single line registers all keywords globally:

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['**/*.Spec.ts'],
    setupFiles: ['@swedevtools/livedoc-vitest/setup'],
    reporters: [
      new LiveDocSpecReporter({ detailLevel: 'spec+summary+headers' }),
    ],
  },
});

The key addition is setupFiles: ['@swedevtools/livedoc-vitest/setup'].

Step 2: Add TypeScript Declarations

For full IntelliSense in your editor, add the LiveDoc globals type to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitest/globals", "@swedevtools/livedoc-vitest/globals"]
  }
}

Step 3: Write a Spec Without Imports

// tests/UserLogin.Spec.ts
// No imports needed!

feature("User Authentication", () => {
  scenario("Successful login with valid credentials", () => {
    given("a registered user with email 'alice@example.com'", (ctx) => {
      const email = ctx.step.values[0]; // "alice@example.com"
      // setup user
    });

    when("they enter the correct password", () => {
      // perform login
    });

    then("they should see the dashboard", () => {
      // assert redirect
    });
  });
});

That's it — no imports, just specs.

Step 4: Run Your Tests

npx vitest run

Output is identical to the explicit imports approach.

Complete Example

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['**/*.Spec.ts'],
    setupFiles: ['@swedevtools/livedoc-vitest/setup'],
    reporters: [
      new LiveDocSpecReporter({ detailLevel: 'spec+summary+headers' }),
    ],
  },
});

// tsconfig.json (relevant parts)
{
  "compilerOptions": {
    "types": ["vitest/globals", "@swedevtools/livedoc-vitest/globals"]
  }
}

// tests/ShoppingCart.Spec.ts

feature(`Shopping Cart
    @checkout @critical
    Core shopping cart operations for the e-commerce platform.
    `, () => {

  scenario("Adding an item increases the cart count", () => {
    given("an empty cart", (ctx) => {
      const cart = { items: [] as string[] };
      ctx.scenario.given = cart;
    });

    when("the user adds 'Wireless Mouse' to the cart", (ctx) => {
      const product = ctx.step.values[0];
      ctx.scenario.given.items.push(product);
    });

    then("the cart contains '1' item", (ctx) => {
      const expectedCount = ctx.step.values[0];
      expect(ctx.scenario.given.items.length).toBe(expectedCount);
    });
  });
});

Common Variations

Adding Global Filter Configuration

Create a custom setup file to configure LiveDoc options for all tests:

// test/livedoc.setup.ts
import { livedoc } from '@swedevtools/livedoc-vitest';

livedoc.options.filters.include = ['@smoke'];
livedoc.options.filters.exclude = ['@slow'];

Then add it after the globals setup file:

// vitest.config.ts
setupFiles: [
  '@swedevtools/livedoc-vitest/setup',
  './test/livedoc.setup.ts',
],

Explicit Imports vs. Globals — Tradeoffs

Aspect	Explicit Imports	Globals Mode
File readability	Good — imports visible	Best — zero boilerplate
IDE autocomplete	Immediate — imports drive it	Requires tsconfig.json types
Portability	Self-contained — works anywhere	Needs matching config
Onboarding	Developers see dependencies	Developers must know globals exist
Code review	Dependencies visible in diff	Cleaner diffs
Refactoring	Rename-safe via imports	Global rename may miss files

Recommendation: Use explicit imports for team projects and libraries. Use globals mode for personal projects or when spec readability is the top priority.

Troubleshooting

Problem	Cause	Solution
ReferenceError: feature is not defined	Missing setup file	Add '@swedevtools/livedoc-vitest/setup' to setupFiles
TypeScript errors on given, when, then	Missing type declarations	Add "@swedevtools/livedoc-vitest/globals" to types in tsconfig.json
globals: true not set	Vitest requires it for global mode	Set globals: true in vitest config
Setup file not found	Wrong path	Use the package path @swedevtools/livedoc-vitest/setup, not a local file
then not working	Should work in globals mode	Verify setup file is loaded — then is lowercase on globalThis

Related

• Setup: Explicit Imports — alternative approach with full imports
• Tags and Filtering — configure global filters in setup files
• Best Practices — choosing between imports and globals
• Configuration — full configuration reference