🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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";