eslint-vitest-rules

name	eslint-vitest-rules
description	Use when setting up ESLint rules for executable-stories-vitest: enforcing the story.init(task) argument requirement, test-context scoping for story.init, or init-before-steps ordering.
type	core
library	eslint-plugin-executable-stories-vitest
library_version	2.1.9
sources	["jagreehal/executable-stories:packages/eslint-plugin-executable-stories-vitest/src/index.ts"]

ESLint Plugin: executable-stories-vitest

Setup

// eslint.config.mjs
import vitestStories from "eslint-plugin-executable-stories-vitest";

export default [
  // Option A: Use recommended config (enables all rules at error)
  ...vitestStories.configs.recommended,

  // Option B: Manual rule configuration
  {
    plugins: {
      "executable-stories-vitest": vitestStories,
    },
    rules: {
      "executable-stories-vitest/require-task-for-story-init": "error",
      "executable-stories-vitest/require-test-context-for-story-init": "error",
      "executable-stories-vitest/require-init-before-steps": "error",
    },
  },
];

Core Patterns

Rule: require-task-for-story-init

Ensures story.init(task) is called with the task argument.

// Fails lint
it("my test", ({ task }) => {
  story.init(); // Error: story.init(task) requires the task argument
});

// Passes lint
it("my test", ({ task }) => {
  story.init(task);
});

Rule: require-test-context-for-story-init

Ensures story.init(task) is called inside a test() or it() callback.

// Fails lint
function helper() {
  story.init(task); // Error: must be inside a test/it callback
}

// Passes lint
it("my test", ({ task }) => {
  story.init(task);
});

// Also detects modifiers: it.only, it.skip, it.todo, it.concurrent, it.fails
it.only("focused test", ({ task }) => {
  story.init(task); // Passes lint
});

Rule: require-init-before-steps

Ensures story.init(task) is called before any step markers.

// Fails lint
it("my test", ({ task }) => {
  story.given("something"); // Error: story.init(task) must be called first
  story.init(task);
});

// Passes lint
it("my test", ({ task }) => {
  story.init(task);
  story.given("something");
});

Detects all step methods: given, when, then, and, but, arrange, act, assert, setup, context, execute, action, verify, fn, expect.

Common Mistakes

HIGH Using legacy .eslintrc instead of flat config

Wrong:

{
  "plugins": ["executable-stories-vitest"],
  "rules": {
    "executable-stories-vitest/require-task-for-story-init": "error"
  }
}

Correct:

// eslint.config.mjs (flat config)
import vitestStories from "eslint-plugin-executable-stories-vitest";

export default [...vitestStories.configs.recommended];

This plugin only supports ESLint 9 flat config. Legacy .eslintrc format is not supported.

Source: packages/eslint-plugin-executable-stories-vitest/src/index.ts

MEDIUM Not scoping rules to story test files

// eslint.config.mjs
import vitestStories from "eslint-plugin-executable-stories-vitest";

export default [
  {
    // Scope to story test files only
    files: ["**/*.story.test.ts", "**/*.story.spec.ts"],
    plugins: {
      "executable-stories-vitest": vitestStories,
    },
    rules: {
      "executable-stories-vitest/require-task-for-story-init": "error",
      "executable-stories-vitest/require-test-context-for-story-init": "error",
      "executable-stories-vitest/require-init-before-steps": "error",
    },
  },
];

Scoping avoids false positives on non-story test files that don't use the story API.

Source: packages/eslint-plugin-executable-stories-vitest/src/index.ts