Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(web): Add no implementation detail assertions eslint rule (#18931)

Ben Bachemc04d528d8b94
diff --git a/packages/eslint-plugin/src/index.ts b/packages/eslint-plugin/src/index.ts
index 6f18c8d78f..35f070147f 100644
--- a/packages/eslint-plugin/src/index.ts
+++ b/packages/eslint-plugin/src/index.ts
@@ -16,6 +16,7 @@ import { default as noSwitchStatements } from "./rules/no-switch-statements.js";
import { default as noUnnecessaryCn } from "./rules/no-unnecessary-cn.js";
import { default as storybookPlayRequiresTestName } from "./rules/storybook-play-requires-test-name.js";
import { default as preferStoriesOverClientTests } from "./rules/prefer-stories-over-client-tests.js";
+import { default as storybookPlayNoImplementationDetailAssertions } from "./rules/storybook-play-no-implementation-detail-assertions.js";
const plugin = {
rules: {
@@ -24,6 +25,8 @@ const plugin = {
"no-arbitrary-colors": noArbitraryColors,
"no-exotic-operators": noExoticOperators,
"no-in-source-vitest": noInSourceVitest,
+ "storybook-play-no-implementation-detail-assertions":
+ storybookPlayNoImplementationDetailAssertions,
"no-margin-on-root-elements": noMarginOnRootElements,
"no-null-render": noNullRender,
"no-let-assign-in-react": noLetAssignInReact,
diff --git a/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.test.ts b/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.test.ts
new file mode 100644
index 0000000000..3aa5082d91
--- /dev/null
+++ b/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.test.ts
@@ -0,0 +1,36 @@
+import { RuleTester } from "@typescript-eslint/rule-tester";
+import * as typescriptEslintParser from "@typescript-eslint/parser";
+import rule from "./storybook-play-no-implementation-detail-assertions.js";
+
+const ruleTester = new RuleTester({
+ languageOptions: { parser: typescriptEslintParser },
+});
+
+ruleTester.run("storybook-play-no-implementation-detail-assertions", rule, {
+ valid: [
+ `const helper = { play: () => expect(element).toHaveClass("active") };`,
+ `export const Default = meta.story({ args: { play: () => expect(element).toHaveClass("active") } });`,
+ `export const Default = meta.story({ play: expect(element).toHaveClass("active") });`,
+ `function helper() { expect(element).toHaveClass("active"); }`,
+ `expect(element).toHaveClass("active");`,
+ `export const Default = meta.story({ render: () => expect(element).toHaveClass("active") });`,
+ `export const Default = meta.story({ play: () => expect(element).toBeVisible() });`,
+ `export const Default = meta.story({ play: () => check(element) });`,
+ `export const Default = meta.story({ play: () => expect(element)[matcher]("active") });`,
+ `export const Default = meta.story({ [key]: () => expect(element).toHaveClass("active") });`,
+ `export const Default = meta.story({ 1: () => expect(element).toHaveClass("active") });`,
+ `Default.render = () => expect(element).toHaveClass("active");`,
+ `Default[key] = () => expect(element).toHaveClass("active");`,
+ `play = () => expect(element).toHaveClass("active");`,
+ ],
+ invalid: [
+ `export const Default = meta["story"]({ play() { expect(element).toHaveClass("active"); } });`,
+ `export const Default = meta.story({ play: async () => { await expect(element).toHaveClass("active"); } });`,
+ `export const Default = { play: () => expect(element).not.toHaveClass("hidden") };`,
+ `export const Default = meta.story({ "play": () => expect(element)["toHaveClass"]("active") });`,
+ `export const Default = meta.story({ ["play"]: () => expect(element).toHaveClass("active") });`,
+ `export const Default = meta.story({ play: async () => { await step("check", () => expect(element).toHaveClass("active")); } });`,
+ `Default.play = () => expect(element).toHaveClass("active");`,
+ `Default["play"] = () => expect(element).toHaveClass("active");`,
+ ].map((code) => ({ code, errors: [{ messageId: "toHaveClass" }] })),
+});
diff --git a/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.ts b/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.ts
new file mode 100644
index 0000000000..71e0548cf4
--- /dev/null
+++ b/packages/eslint-plugin/src/rules/storybook-play-no-implementation-detail-assertions.ts
@@ -0,0 +1,50 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import { createRule } from "../util.js";
+import {
+ getStaticPropertyName,
+ isStorybookPlayFunction,
+} from "../storybook.js";
+
+const rule = createRule({
+ name: "storybook-play-no-implementation-detail-assertions",
+ meta: {
+ type: "suggestion",
+ docs: {
+ description:
+ "Disallow assertions about implementation details in Storybook play functions.",
+ },
+ schema: [],
+ messages: {
+ toHaveClass:
+ "Do not use toHaveClass in Storybook play functions. If the assertion only checks styling and the styling does not have consequences on behavior, remove it. CSS classes are implementation details: changing styling or refactoring markup can break this assertion without changing what users experience. Assert observable behavior instead, such as visible content, accessible state, focus, or the result of an interaction.",
+ },
+ },
+ defaultOptions: [],
+ create(context) {
+ return {
+ CallExpression(node) {
+ const callee = node.callee;
+ if (callee.type !== AST_NODE_TYPES.MemberExpression) return;
+
+ if (getStaticPropertyName(callee) !== "toHaveClass") return;
+
+ for (
+ let ancestor: TSESTree.Node | undefined = node.parent;
+ ancestor;
+ ancestor = ancestor.parent
+ ) {
+ if (
+ (ancestor.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+ ancestor.type === AST_NODE_TYPES.FunctionExpression) &&
+ isStorybookPlayFunction(ancestor)
+ ) {
+ context.report({ node: callee.property, messageId: "toHaveClass" });
+ return;
+ }
+ }
+ },
+ };
+ },
+});
+
+export default rule;
diff --git a/packages/eslint-plugin/src/rules/storybook-play-requires-test-name.ts b/packages/eslint-plugin/src/rules/storybook-play-requires-test-name.ts
index 8a8ab99e41..1dccc03974 100644
--- a/packages/eslint-plugin/src/rules/storybook-play-requires-test-name.ts
+++ b/packages/eslint-plugin/src/rules/storybook-play-requires-test-name.ts
@@ -1,41 +1,9 @@
import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
import { createRule } from "../util.js";
+import { getStaticPropertyName, isStoryObject } from "../storybook.js";
const TEST_STORY_PREFIX = "(Test)";
-function getPropertyName(property: TSESTree.Property): string | null {
- if (property.computed) return null;
- if (property.key.type === AST_NODE_TYPES.Identifier) return property.key.name;
- if (
- property.key.type === AST_NODE_TYPES.Literal &&
- typeof property.key.value === "string"
- ) {
- return property.key.value;
- }
- return null;
-}
-
-function isStoryObject(node: TSESTree.ObjectExpression): boolean {
- const parent = node.parent;
-
- if (
- parent.type === AST_NODE_TYPES.CallExpression &&
- parent.arguments[0] === node &&
- parent.callee.type === AST_NODE_TYPES.MemberExpression &&
- !parent.callee.computed &&
- parent.callee.property.type === AST_NODE_TYPES.Identifier &&
- parent.callee.property.name === "story"
- ) {
- return true;
- }
-
- return (
- parent.type === AST_NODE_TYPES.VariableDeclarator &&
- parent.init === node &&
- parent.parent.parent.type === AST_NODE_TYPES.ExportNamedDeclaration
- );
-}
-
const rule = createRule({
name: "storybook-play-requires-test-name",
meta: {
@@ -61,12 +29,14 @@ const rule = createRule({
property.type === AST_NODE_TYPES.Property,
);
const playProperty = properties.find(
- (property) => getPropertyName(property) === "play",
+ (property) =>
+ !property.computed && getStaticPropertyName(property) === "play",
);
if (!playProperty) return;
const nameProperty = properties.find(
- (property) => getPropertyName(property) === "name",
+ (property) =>
+ !property.computed && getStaticPropertyName(property) === "name",
);
const name =
nameProperty?.value.type === AST_NODE_TYPES.Literal &&
diff --git a/packages/eslint-plugin/src/storybook.ts b/packages/eslint-plugin/src/storybook.ts
new file mode 100644
index 0000000000..280caf75bf
--- /dev/null
+++ b/packages/eslint-plugin/src/storybook.ts
@@ -0,0 +1,51 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+export function getStaticPropertyName(
+ node: TSESTree.Property | TSESTree.MemberExpression,
+): string | null {
+ const key = node.type === AST_NODE_TYPES.Property ? node.key : node.property;
+ if (!node.computed && key.type === AST_NODE_TYPES.Identifier) return key.name;
+ if (key.type === AST_NODE_TYPES.Literal && typeof key.value === "string") {
+ return key.value;
+ }
+ return null;
+}
+
+export function isStoryObject(node: TSESTree.ObjectExpression): boolean {
+ const parent = node.parent;
+ if (
+ parent.type === AST_NODE_TYPES.CallExpression &&
+ parent.arguments[0] === node &&
+ parent.callee.type === AST_NODE_TYPES.MemberExpression &&
+ getStaticPropertyName(parent.callee) === "story"
+ ) {
+ return true;
+ }
+ return (
+ parent.type === AST_NODE_TYPES.VariableDeclarator &&
+ parent.init === node &&
+ parent.parent.parent.type === AST_NODE_TYPES.ExportNamedDeclaration
+ );
+}
+
+export function isStorybookPlayFunction(
+ node: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression,
+): boolean {
+ const parent = node.parent;
+ if (parent.type === AST_NODE_TYPES.Property) {
+ return (
+ parent.value === node &&
+ getStaticPropertyName(parent) === "play" &&
+ parent.parent.type === AST_NODE_TYPES.ObjectExpression &&
+ isStoryObject(parent.parent)
+ );
+ }
+ if (parent.type === AST_NODE_TYPES.AssignmentExpression) {
+ return (
+ parent.right === node &&
+ parent.left.type === AST_NODE_TYPES.MemberExpression &&
+ getStaticPropertyName(parent.left) === "play"
+ );
+ }
+ return false;
+}
diff --git a/web/eslint.config.mjs b/web/eslint.config.mjs
index 212ec763b3..d7d29355ba 100644
--- a/web/eslint.config.mjs
+++ b/web/eslint.config.mjs
@@ -94,6 +94,7 @@ export default [
files: ["src/**/*.stories.{ts,tsx}"],
rules: {
"@repo/storybook-play-requires-test-name": "error",
+ "@repo/storybook-play-no-implementation-detail-assertions": "warn",
},
},
{
diff --git a/web/src/components/design-system/Alert/Alert.stories.tsx b/web/src/components/design-system/Alert/Alert.stories.tsx
index 0de0aa41db..b0e3c5a453 100644
--- a/web/src/components/design-system/Alert/Alert.stories.tsx
+++ b/web/src/components/design-system/Alert/Alert.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import React from "react";
import { AlertTriangle, Info, X } from "lucide-react";
import { expect, fn, userEvent, within } from "storybook/test";
diff --git a/web/src/components/design-system/ControlledHoverCard/ControlledHoverCard.stories.tsx b/web/src/components/design-system/ControlledHoverCard/ControlledHoverCard.stories.tsx
index d4f543e69a..c2e7a422e5 100644
--- a/web/src/components/design-system/ControlledHoverCard/ControlledHoverCard.stories.tsx
+++ b/web/src/components/design-system/ControlledHoverCard/ControlledHoverCard.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import * as React from "react";
import {
expect,
diff --git a/web/src/components/design-system/HoverCard/HoverCard.stories.tsx b/web/src/components/design-system/HoverCard/HoverCard.stories.tsx
index 412abcde1c..f670e2c780 100644
--- a/web/src/components/design-system/HoverCard/HoverCard.stories.tsx
+++ b/web/src/components/design-system/HoverCard/HoverCard.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import * as React from "react";
import { expect, fn, userEvent, waitFor, within } from "storybook/test";
diff --git a/web/src/components/design-system/KeyboardShortcut/KeyboardShortcut.stories.tsx b/web/src/components/design-system/KeyboardShortcut/KeyboardShortcut.stories.tsx
index 094f1e188c..b9d2e2f277 100644
--- a/web/src/components/design-system/KeyboardShortcut/KeyboardShortcut.stories.tsx
+++ b/web/src/components/design-system/KeyboardShortcut/KeyboardShortcut.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { expect, within } from "storybook/test";
import preview from "../../../../.storybook/preview";
diff --git a/web/src/components/design-system/Tooltip/Tooltip.stories.tsx b/web/src/components/design-system/Tooltip/Tooltip.stories.tsx
index 9f549b6d2b..e0954e0b22 100644
--- a/web/src/components/design-system/Tooltip/Tooltip.stories.tsx
+++ b/web/src/components/design-system/Tooltip/Tooltip.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { expect, userEvent, waitFor, within } from "storybook/test";
import preview from "../../../../.storybook/preview";
diff --git a/web/src/components/design-system/charts/ChartTooltip.stories.tsx b/web/src/components/design-system/charts/ChartTooltip.stories.tsx
index 8859f65fee..818a48eab9 100644
--- a/web/src/components/design-system/charts/ChartTooltip.stories.tsx
+++ b/web/src/components/design-system/charts/ChartTooltip.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { type ComponentProps } from "react";
import preview from "../../../../.storybook/preview";
import { expect, spyOn, userEvent, within } from "storybook/test";
diff --git a/web/src/components/design-system/table/columns/createIOTableColumn.stories.tsx b/web/src/components/design-system/table/columns/createIOTableColumn.stories.tsx
index 341caa1854..704cd5756b 100644
--- a/web/src/components/design-system/table/columns/createIOTableColumn.stories.tsx
+++ b/web/src/components/design-system/table/columns/createIOTableColumn.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import preview from "../../../../../.storybook/preview";
import { expect } from "storybook/test";
diff --git a/web/src/components/table/DataTable.stories.tsx b/web/src/components/table/DataTable.stories.tsx
index c3e1aa0cc1..8d51521a5c 100644
--- a/web/src/components/table/DataTable.stories.tsx
+++ b/web/src/components/table/DataTable.stories.tsx
@@ -1,4 +1,4 @@
-/* eslint-disable no-nested-ternary */
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions, no-nested-ternary */
import preview from "../../../.storybook/preview";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { expect, fireEvent, fn } from "storybook/test";
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.stories.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.stories.tsx
index 121c1d2924..c56b585ef3 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.stories.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import type { ComponentProps } from "react";
import { expect, fn, screen, userEvent, waitFor } from "storybook/test";
diff --git a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/components/PromptEditor/PromptEditor.stories.tsx b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/components/PromptEditor/PromptEditor.stories.tsx
index c6b7c0e279..83a63fd1a6 100644
--- a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/components/PromptEditor/PromptEditor.stories.tsx
+++ b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/components/PromptEditor/PromptEditor.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { useState, type ComponentProps } from "react";
import { expect, userEvent, within } from "storybook/test";
diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/SessionConversationalView.stories.tsx b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/SessionConversationalView.stories.tsx
index fbc521d2f9..362e6856c6 100644
--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/SessionConversationalView.stories.tsx
+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/SessionConversationalView.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { orderObservations } from "@langfuse/shared/src/server/transcript/ordering";
import { assembleTranscript } from "@langfuse/shared/src/server/transcript/transcript";
import { type TranscriptObservation } from "@langfuse/shared/src/server/transcript/types";
diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineContentMessage/SessionTimelineContentMessage.stories.tsx b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineContentMessage/SessionTimelineContentMessage.stories.tsx
index 66a7ad086d..92b6299cc0 100644
--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineContentMessage/SessionTimelineContentMessage.stories.tsx
+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineContentMessage/SessionTimelineContentMessage.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import preview from "@/.storybook/preview";
import { expect, fn, userEvent, waitFor, within } from "storybook/test";
diff --git a/web/src/features/traces/components/BreakdownTooltip.stories.tsx b/web/src/features/traces/components/BreakdownTooltip.stories.tsx
index 1076f1e636..ccc2c5ba30 100644
--- a/web/src/features/traces/components/BreakdownTooltip.stories.tsx
+++ b/web/src/features/traces/components/BreakdownTooltip.stories.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable @repo/storybook-play-no-implementation-detail-assertions */
import { expect, userEvent, waitFor, within } from "storybook/test";
import preview from "../../../../.storybook/preview";