diff --git a/apps/backend/src/database/seeds.ts b/apps/backend/src/database/seeds.ts index edb095462..bf7bbb6a4 100644 --- a/apps/backend/src/database/seeds.ts +++ b/apps/backend/src/database/seeds.ts @@ -1287,6 +1287,213 @@ export async function createVariantSwitchersScenario(input: { return { build, variantKey }; } +/** + * A build whose screenshots come from a test that walks a checkout step by + * step, with the SDK's capture order recorded — plus one screenshot from a + * test that is not a journey. Names are chosen so that neither the + * alphabetical order (cart, confirmation, payment, shipping) nor the diff + * score order matches the journey (cart, shipping, payment, confirmation): + * a drawer that follows the journey can only be following the metadata. + * + * Two of the four steps are unchanged, so the journey is only whole if it is + * built from every diff of the build rather than from the reviewable ones. + */ +export async function createJourneyScenario(input: { + projectId: string; +}): Promise<{ build: Build }> { + const { projectId } = input; + const seededAt = getSeedInstant(); + const sdk = { name: "@argos-ci/playwright", version: "6.0.0" }; + const automationLibrary = { name: "playwright", version: "1.61.0" }; + const browser = { name: "chromium", version: "126.0" }; + const viewport = { width: 375, height: 1024 }; + + const steps: { + name: string; + index: number; + /** Diff score; `null` for an unchanged screenshot. */ + score: number | null; + }[] = [ + { name: "checkout/cart.png", index: 0, score: null }, + { name: "checkout/shipping.png", index: 1, score: null }, + { name: "checkout/payment.png", index: 2, score: 0.3 }, + // Scores higher than the payment step, so the server (score first) lists + // it before payment while the journey puts it after. + { name: "checkout/confirmation.png", index: 3, score: 0.5 }, + ]; + const journey = { + title: "complete a purchase", + titlePath: ["checkout.spec.ts", "complete a purchase"], + location: { file: "e2e/checkout.spec.ts", line: 8, column: 5 }, + retries: 0, + retry: 0, + }; + const other = { + name: "account/settings.png", + score: 0.1, + test: { + title: "shows the account settings", + titlePath: ["account.spec.ts", "shows the account settings"], + location: { file: "e2e/account.spec.ts", line: 4, column: 5 }, + retries: 0, + retry: 0, + }, + }; + + const bucketProps = { + name: "default", + projectId, + complete: true, + valid: true, + screenshotCount: steps.length + 1, + storybookScreenshotCount: 0, + createdAt: seededAt, + updatedAt: seededAt, + }; + const [baseBucket, compareBucket] = + await ScreenshotBucket.query().insertAndFetch([ + { + ...bucketProps, + branch: "main", + commit: "5f1e0c2b7a9d4e6f8c3b1a0d9e7f6c5b4a3d2e1f", + }, + { + ...bucketProps, + branch: "feat/apple-pay", + commit: "9c8b7a6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b", + }, + ]); + invariant(baseBucket && compareBucket); + + const [baseFile, compareFile, diffFile] = await Promise.all([ + ensureFile({ + type: "screenshot", + width: 375, + height: 1024, + key: "dummy-375x1024.png", + contentType: "image/png", + }), + ensureFile({ + type: "screenshot", + width: 375, + height: 720, + key: "dummy-375x720.png", + contentType: "image/png", + }), + ensureFile({ + type: "screenshotDiff", + width: 375, + height: 1024, + key: "diff-1024-to-720.png", + contentType: "image/png", + }), + ]); + + const screenshots = [ + ...steps.map((step) => ({ + name: step.name, + score: step.score, + metadata: { + url: `https://shop.example.com/${step.name.replace(/\.png$/, "")}`, + viewport, + colorScheme: "light" as const, + mediaType: "screen" as const, + test: journey, + capture: { index: step.index }, + browser, + automationLibrary, + sdk, + } satisfies ScreenshotMetadata, + })), + { + name: other.name, + score: other.score, + metadata: { + url: "https://shop.example.com/account/settings", + viewport, + colorScheme: "light" as const, + mediaType: "screen" as const, + test: other.test, + capture: { index: 0 }, + browser, + automationLibrary, + sdk, + } satisfies ScreenshotMetadata, + }, + ]; + + const tests = await Test.query().insertAndFetch( + screenshots.map((screenshot) => ({ + name: screenshot.name, + buildName: "default", + projectId, + })), + ); + const testIdByName = new Map(tests.map((test) => [test.name, test.id])); + + const baseScreenshots = await Screenshot.query().insertAndFetch( + screenshots.map((screenshot) => ({ + screenshotBucketId: baseBucket.id, + testId: testIdByName.get(screenshot.name) ?? null, + name: screenshot.name, + s3Id: baseFile.key, + fileId: baseFile.id, + metadata: screenshot.metadata, + })), + ); + const compareScreenshots = await Screenshot.query().insertAndFetch( + screenshots.map((screenshot) => ({ + screenshotBucketId: compareBucket.id, + testId: testIdByName.get(screenshot.name) ?? null, + name: screenshot.name, + s3Id: screenshot.score === null ? baseFile.key : compareFile.key, + fileId: screenshot.score === null ? baseFile.id : compareFile.id, + metadata: screenshot.metadata, + })), + ); + + const [build] = await Build.query().insertAndFetch([ + { + name: "default", + number: 1, + type: "check" as const, + jobStatus: "complete" as const, + baseScreenshotBucketId: baseBucket.id, + compareScreenshotBucketId: compareBucket.id, + baseBranch: "main", + projectId, + createdAt: seededAt, + updatedAt: seededAt, + }, + ]); + invariant(build); + + await ScreenshotDiff.query().insert( + screenshots.map((screenshot, index) => { + const baseScreenshot = baseScreenshots[index]; + const compareScreenshot = compareScreenshots[index]; + invariant(baseScreenshot && compareScreenshot); + const changed = screenshot.score !== null; + return { + buildId: build.id, + baseScreenshotId: baseScreenshot.id, + compareScreenshotId: compareScreenshot.id, + testId: testIdByName.get(screenshot.name) ?? null, + score: screenshot.score ?? 0, + jobStatus: "complete" as const, + s3Id: changed ? diffFile.key : null, + fileId: changed ? diffFile.id : null, + createdAt: seededAt, + updatedAt: seededAt, + }; + }), + ); + + await concludeBuild({ build, notify: false }); + + return { build }; +} + /** * Three builds sharing one head commit and branch — the shape a commit gets * when it runs several suites, and when a monorepo splits them over several @@ -2130,6 +2337,15 @@ export async function seed() { projectId: bigProject.id, }); + // Its own project: the scenario owns build 1 and its buckets, which would + // collide with the builds `bigProject` already carries. + const journeyProject = await createProject({ + name: "checkout", + token: "checkout-3f0b9c1d4e2a8b7c6d5e4f3a2b1c0d9e8f7a", + accountId: smoothAccount.id, + }); + await createJourneyScenario({ projectId: journeyProject.id }); + await createDeploymentScenario({ projectId: bigProject.id, accountSlug: smoothAccount.slug, diff --git a/apps/backend/src/graphql/definitions/Screenshot.ts b/apps/backend/src/graphql/definitions/Screenshot.ts index 515110b9e..9f54aacf5 100644 --- a/apps/backend/src/graphql/definitions/Screenshot.ts +++ b/apps/backend/src/graphql/definitions/Screenshot.ts @@ -78,6 +78,10 @@ export const typeDefs = gql` play: Boolean } + type ScreenshotMetadataCapture { + index: Int! + } + type ScreenshotMetadata { url: String previewUrl: String @@ -89,6 +93,7 @@ export const typeDefs = gql` automationLibrary: ScreenshotMetadataAutomationLibrary! sdk: ScreenshotMetadataSDK! story: ScreenshotMetadataStory + capture: ScreenshotMetadataCapture tags: [String!] } diff --git a/apps/frontend/src/containers/Build/hotkeys.ts b/apps/frontend/src/containers/Build/hotkeys.ts index 36d40020a..f8d5ddfb1 100644 --- a/apps/frontend/src/containers/Build/hotkeys.ts +++ b/apps/frontend/src/containers/Build/hotkeys.ts @@ -101,6 +101,18 @@ const hotkeyGroups = [ description: "Go to next media", envs: ["media"], }, + goToPreviousJourneyStep: { + keys: ["⇧", "ArrowLeft"], + displayKeys: ["⇧", "←"], + description: "Go to previous journey step", + envs: ["build"], + }, + goToNextJourneyStep: { + keys: ["⇧", "ArrowRight"], + displayKeys: ["⇧", "→"], + description: "Go to next journey step", + envs: ["build"], + }, toggleDiffGroup: { keys: ["KeyG"], displayKeys: ["G"], diff --git a/apps/frontend/src/pages/Build/BuildDetailHeader.tsx b/apps/frontend/src/pages/Build/BuildDetailHeader.tsx index 3e293b23a..21fbd742b 100644 --- a/apps/frontend/src/pages/Build/BuildDetailHeader.tsx +++ b/apps/frontend/src/pages/Build/BuildDetailHeader.tsx @@ -25,6 +25,7 @@ import { useHasNextDiff, useHasPreviousDiff, } from "./BuildDiffState"; +import { JourneyDrawerToggle } from "./BuildJourneyDrawer"; import { VariantSwitchers } from "./metadata/variants/VariantSwitchers"; import { RightSidebarToggle } from "./RightSidebar"; @@ -94,6 +95,7 @@ export const BuildDetailHeader = memo(function BuildDetailHeader(props: { snapshotControls={false} fitControls={} > + diff --git a/apps/frontend/src/pages/Build/BuildDiffState.tsx b/apps/frontend/src/pages/Build/BuildDiffState.tsx index 274abc63a..67744a83f 100644 --- a/apps/frontend/src/pages/Build/BuildDiffState.tsx +++ b/apps/frontend/src/pages/Build/BuildDiffState.tsx @@ -33,11 +33,19 @@ import { } from "./BuildParams"; import { useBuildReviewState } from "./BuildReviewState"; import { EvaluationStatus } from "./EvaluationStatus"; +import { + compareSteps, + getCaptureIndex, + getVariantSignature, + resolveJourneyIdentity, + type JourneyIdentity, +} from "./journey-model"; import { FilterStateContext } from "./metadata/filters/FilterState"; import { diffMatchesFilters, useCreateFilterState, } from "./metadata/filters/util"; +import { resolveDiffMetadata } from "./metadata/utils"; // eslint-disable-next-line @typescript-eslint/no-unused-vars const ScreenshotDiffFragment = graphql(` @@ -85,6 +93,9 @@ const ScreenshotDiffFragment = graphql(` play tags } + capture { + index + } viewport { width height @@ -147,6 +158,9 @@ const ScreenshotDiffFragment = graphql(` play tags } + capture { + index + } viewport { width height @@ -624,6 +638,108 @@ const INITIAL_EXPANDED = [ ScreenshotDiffStatus.Removed, ]; +/** + * Visibility of the journey drawer in the build detail, persisted as a user + * preference. + */ +const JOURNEY_DRAWER_STORAGE_KEY = "preferences.build.journey-drawer"; + +type JourneyDrawerContextValue = { + visible: boolean; + setVisible: (visible: boolean) => void; +}; + +const JourneyDrawerContext = createContext( + null, +); + +export function useJourneyDrawerState() { + const context = use(JourneyDrawerContext); + invariant( + context, + "useJourneyDrawerState must be used within a BuildDiffProvider", + ); + return context; +} + +export type ActiveDiffJourney = { + identity: JourneyIdentity; + /** The steps of the journey in order, each with its variants. */ + steps: { key: string; diffs: Diff[] }[]; + /** Position of the active diff's step in `steps`. */ + stepIndex: number; +}; + +/** + * The journey context of the active diff: the journey it belongs to, its steps + * (variants collapsed) in order, and the active step position. Null when the + * active diff has no journey information or the journey has a single step — + * a test that captures one screen is regular visual testing, not a journey. + * + * Built from `allDiffs`, not from the filtered list: a journey is worth showing + * whole, so the screens that did not change are in it too, and the drawer marks + * the ones that did. + */ +export function useActiveDiffJourney(): ActiveDiffJourney | null { + const { activeDiff, allDiffs } = useBuildDiffState(); + return useMemo(() => { + if (!activeDiff) { + return null; + } + const identity = resolveJourneyIdentity(resolveDiffMetadata(activeDiff)); + if (!identity) { + return null; + } + const stepMap = new Map< + string, + { key: string; captureIndex: number | null; diffs: Diff[] } + >(); + for (const diff of allDiffs) { + const metadata = resolveDiffMetadata(diff); + if (resolveJourneyIdentity(metadata)?.key !== identity.key) { + continue; + } + const key = diff.variantKey; + const step = stepMap.get(key) ?? { key, captureIndex: null, diffs: [] }; + stepMap.set(key, step); + step.diffs.push(diff); + const captureIndex = getCaptureIndex(metadata); + if (captureIndex !== null) { + step.captureIndex = Math.min( + step.captureIndex ?? Number.MAX_SAFE_INTEGER, + captureIndex, + ); + } + } + const steps = [...stepMap.values()].toSorted(compareSteps); + if (steps.length < 2) { + return null; + } + return { + identity, + steps, + stepIndex: steps.findIndex((step) => step.key === activeDiff.variantKey), + }; + }, [activeDiff, allDiffs]); +} + +/** + * The diff of `step` that is the same variant as `reference` (same browser, + * viewport, scheme…), or the step's first diff when that variant is missing. + * Moving between steps stays on one viewport this way. + */ +export function pickStepDiff( + step: ActiveDiffJourney["steps"][number], + reference: Diff, +): Diff | null { + const signature = getVariantSignature(reference); + return ( + step.diffs.find((diff) => getVariantSignature(diff) === signature) ?? + step.diffs[0] ?? + null + ); +} + export function BuildDiffProvider(props: { children: React.ReactNode; build: DocumentType | null; @@ -727,6 +843,21 @@ export function BuildDiffProvider(props: { const [scrolledDiff, setScrolledDiff] = useState(null); + const [drawerVisible, setDrawerVisibleState] = useState( + () => localStorage.getItem(JOURNEY_DRAWER_STORAGE_KEY) === "true", + ); + const setDrawerVisible = useCallback((visible: boolean) => { + localStorage.setItem(JOURNEY_DRAWER_STORAGE_KEY, String(visible)); + setDrawerVisibleState(visible); + }, []); + const drawerValue = useMemo( + (): JourneyDrawerContextValue => ({ + visible: drawerVisible, + setVisible: setDrawerVisible, + }), + [drawerVisible, setDrawerVisible], + ); + const groups = useMemo(() => { return groupDiffs(filteredDiffs, reviewState?.diffStatuses ?? {}); }, [filteredDiffs, reviewState?.diffStatuses]); @@ -845,7 +976,9 @@ export function BuildDiffProvider(props: { - {children} + + {children} + diff --git a/apps/frontend/src/pages/Build/BuildJourneyDrawer.tsx b/apps/frontend/src/pages/Build/BuildJourneyDrawer.tsx new file mode 100644 index 000000000..0465fa3df --- /dev/null +++ b/apps/frontend/src/pages/Build/BuildJourneyDrawer.tsx @@ -0,0 +1,205 @@ +import { clsx } from "clsx"; +import { ChevronRightIcon, WaypointsIcon } from "lucide-react"; + +import { + type DiffGroupName, + getDiffGroupDefinition, +} from "@/containers/Build/BuildDiffGroup"; +import { useBuildHotkey } from "@/containers/Build/BuildHotkeys"; +import { ScreenshotDiffStatus } from "@/gql/graphql"; +import { Button } from "@/ui/Button"; +import { Tooltip } from "@/ui/Tooltip"; +import { useEventCallback } from "@/ui/useEventCallback"; + +import { + type ActiveDiffJourney, + pickStepDiff, + useActiveDiffJourney, + useBuildDiffState, + useJourneyDrawerState, +} from "./BuildDiffState"; +import { getStepLabel } from "./journey-model"; +import { getViewportIconKind } from "./metadata/metadataIcons"; +import { resolveDiffMetadata } from "./metadata/utils"; +import { ScreenshotDiffThumbnail } from "./sidebar/ScreenshotDiffThumbnail"; + +/** + * ⇧← / ⇧→ walk the journey of the active diff, across status sections — the + * keyboard counterpart of the drawer (and independent from it). + */ +export function JourneyStepHotkeys() { + const journey = useActiveDiffJourney(); + const { activeDiff, setActiveDiff } = useBuildDiffState(); + const goToStep = useEventCallback((delta: -1 | 1) => { + if (!journey || !activeDiff) { + return; + } + const target = journey.steps[journey.stepIndex + delta]; + if (!target) { + return; + } + const diff = pickStepDiff(target, activeDiff); + if (diff) { + setActiveDiff(diff, true); + } + }); + useBuildHotkey("goToPreviousJourneyStep", () => goToStep(-1), { + preventDefault: true, + }); + useBuildHotkey("goToNextJourneyStep", () => goToStep(1), { + preventDefault: true, + }); + return null; +} + +/** What the dot marks: the statuses that put a diff in front of a reviewer. */ +const ATTENTION_STATUSES = [ + ScreenshotDiffStatus.Failure, + ScreenshotDiffStatus.Changed, + ScreenshotDiffStatus.Added, + ScreenshotDiffStatus.Removed, +] as const satisfies DiffGroupName[]; + +/** + * The statuses of a step worth a reviewer's attention, named as the rest of the + * review names them, in the order the diff list sections come in. + */ +function getAttentionLabels( + step: ActiveDiffJourney["steps"][number], +): string[] { + const statuses = new Set(step.diffs.map((diff) => diff.status)); + return ATTENTION_STATUSES.filter((status) => statuses.has(status)).map( + (status) => getDiffGroupDefinition(status).label, + ); +} + +/** + * The journey of the active diff as a strip of steps, on demand: shows where + * the change sits in the journey and jumps between steps. Only rendered when + * the user asked for it and the active diff belongs to a multi-step journey. + */ +export function BuildJourneyDrawer() { + const { visible } = useJourneyDrawerState(); + const journey = useActiveDiffJourney(); + const { activeDiff, setActiveDiff } = useBuildDiffState(); + if (!visible || !journey || !activeDiff) { + return null; + } + // The strip stays within the active diff's variant, so every box shares one + // viewport: it can take its shape from it, portrait for a mobile run. + const viewportWidth = resolveDiffMetadata(activeDiff)?.viewport?.width; + const portrait = + viewportWidth !== undefined && + getViewportIconKind(viewportWidth) === "mobile"; + return ( + // An inset card in the viewer column, aligned on the diff area gutters + // (`p-4`) and styled like the diff panels. The inner padding keeps the + // selection ring and focus outline of edge thumbnails from being clipped + // by the scroll container. +
+
+ {journey.steps.map((step, index) => { + const diff = pickStepDiff(step, activeDiff); + if (!diff) { + return null; + } + const isActive = index === journey.stepIndex; + const attentionLabels = getAttentionLabels(step); + return ( +
+ {index > 0 && ( + + )} + +
+ ); + })} +
+
+ ); +} + +/** + * Opens the drawer, and is the only sign a journey exists when it is closed — + * so it renders only when the active diff belongs to one. + */ +export function JourneyDrawerToggle() { + const journey = useActiveDiffJourney(); + const { visible, setVisible } = useJourneyDrawerState(); + if (!journey) { + return null; + } + return ( + + + + ); +} diff --git a/apps/frontend/src/pages/Build/BuildWorkspace.tsx b/apps/frontend/src/pages/Build/BuildWorkspace.tsx index fcd535bd1..3288baaa3 100644 --- a/apps/frontend/src/pages/Build/BuildWorkspace.tsx +++ b/apps/frontend/src/pages/Build/BuildWorkspace.tsx @@ -17,6 +17,7 @@ import { Code } from "../../ui/Code"; import { Link } from "../../ui/Link"; import { BuildDetailHeader } from "./BuildDetailHeader"; import { useBuildDiffState } from "./BuildDiffState"; +import { BuildJourneyDrawer, JourneyStepHotkeys } from "./BuildJourneyDrawer"; import { BuildOverview } from "./BuildOverview"; import { BuildParams } from "./BuildParams"; import { BuildLeftSidebar } from "./LeftSidebar"; @@ -119,47 +120,53 @@ export function BuildWorkspace(props: {
+
- {(() => { - switch (build.status) { - case BuildStatus.Aborted: - case BuildStatus.Error: - case BuildStatus.Expired: - return ( -
- - - { +
+ + {(() => { + switch (build.status) { + case BuildStatus.Aborted: + case BuildStatus.Error: + case BuildStatus.Expired: + return ( +
+ + { - [BuildStatus.Error]: "Build failed", - [BuildStatus.Expired]: "Build expired", - [BuildStatus.Aborted]: "Build aborted", - }[build.status] - } - - - - - -
- ); - case BuildStatus.Pending: - case BuildStatus.Progress: - return ; - default: - if ( - !params.diffId && - build.type !== BuildType.Skipped && - ((build.stats?.total ?? 0) > 0 || - build.type === BuildType.Orphan) - ) { - return ; - } + { + [BuildStatus.Error]: "Build failed", + [BuildStatus.Expired]: "Build expired", + [BuildStatus.Aborted]: "Build aborted", + }[build.status] + } + + + + + +
+ ); + case BuildStatus.Pending: + case BuildStatus.Progress: + return ; + default: + if ( + !params.diffId && + build.type !== BuildType.Skipped && + ((build.stats?.total ?? 0) > 0 || + build.type === BuildType.Orphan) + ) { + return ( + + ); + } - return build && ; - } - })()} + return build && ; + } + })()} +
{ + it("groups by test title path", () => { + expect( + resolveJourneyIdentity({ + test: { titlePath: ["checkout.spec.ts", "complete a purchase"] }, + }), + ).toEqual({ + key: "checkout.spec.ts › complete a purchase", + prefix: "checkout.spec.ts", + title: "complete a purchase", + }); + }); + + it("groups stories by component", () => { + expect( + resolveJourneyIdentity({ + story: { id: "components-button--primary" }, + test: { + titlePath: ["storybook.spec.ts", "components-button--primary"], + }, + }), + ).toEqual({ + key: "storybook › components-button", + prefix: "storybook", + title: "components-button", + }); + }); + + it("returns null without test or story metadata", () => { + expect(resolveJourneyIdentity(null)).toBeNull(); + expect(resolveJourneyIdentity({})).toBeNull(); + expect(resolveJourneyIdentity({ test: { titlePath: [] } })).toBeNull(); + expect( + resolveJourneyIdentity({ test: { titlePath: [" ", ""] } }), + ).toBeNull(); + }); +}); + +describe("#getVariantSignature", () => { + it("keeps what tells variants apart", () => { + expect( + getVariantSignature({ + name: "chromium/checkout/cart vw-375.png", + variantKey: "checkout/cart", + }), + ).toBe("chromium/ vw-375.png"); + expect( + getVariantSignature({ + name: "chromium/checkout/payment vw-375.png", + variantKey: "checkout/payment", + }), + ).toBe("chromium/ vw-375.png"); + // Same step, two viewports: different signatures. + expect( + getVariantSignature({ + name: "chromium/checkout/cart vw-1280.png", + variantKey: "checkout/cart", + }), + ).toBe("chromium/ vw-1280.png"); + }); +}); + +describe("#getStepLabel", () => { + it("keeps the last path segment", () => { + expect(getStepLabel("checkout/cart")).toBe("cart"); + expect(getStepLabel("cart")).toBe("cart"); + }); +}); + +describe("#compareSteps", () => { + it("follows the capture order, then the key", () => { + const steps = [ + { key: "b", captureIndex: null }, + { key: "z", captureIndex: 0 }, + { key: "a", captureIndex: null }, + { key: "y", captureIndex: 1 }, + ]; + expect(steps.toSorted(compareSteps).map((step) => step.key)).toEqual([ + "z", + "y", + "a", + "b", + ]); + }); +}); + +describe("#getCaptureIndex", () => { + it("reads the index the SDK recorded", () => { + expect(getCaptureIndex({ capture: { index: 0 } })).toBe(0); + expect(getCaptureIndex({ capture: { index: 3 } })).toBe(3); + }); + + it("returns null when the SDK is too old to record it", () => { + expect(getCaptureIndex(null)).toBeNull(); + expect(getCaptureIndex({})).toBeNull(); + expect(getCaptureIndex({ capture: null })).toBeNull(); + }); +}); diff --git a/apps/frontend/src/pages/Build/journey-model.ts b/apps/frontend/src/pages/Build/journey-model.ts new file mode 100644 index 000000000..00b255b9d --- /dev/null +++ b/apps/frontend/src/pages/Build/journey-model.ts @@ -0,0 +1,99 @@ +/** + * The journey a screenshot belongs to, derived from the metadata the SDK + * records — nothing to configure on the user's side. + * + * A *journey* is the test that took the screenshot: its title path (file › + * describe › test) is the identity. Storybook uploads carry a story id + * instead: stories group by component, one step per story. + * + * A *step* is a logical screen, not a file: the viewport and browser variants + * of one screen collapse into one step, keyed by the backend `variantKey`. + * Steps follow the capture order recorded by the SDK, and fall back to the + * alphabetical order of their key when it is missing. + */ + +/** The part of a screenshot's metadata the journey model reads. */ +export type JourneyMetadata = { + test?: { titlePath: string[] } | null; + story?: { id: string } | null; + capture?: { index: number } | null; +} | null; + +export type JourneyIdentity = { + /** Stable key, e.g. the joined test title path or a story component id. */ + key: string; + /** Muted context shown before the title (test file, "storybook"…). */ + prefix: string; + title: string; +}; + +export function resolveJourneyIdentity( + metadata: JourneyMetadata, +): JourneyIdentity | null { + // Story first: Storybook runs through a Playwright test runner, so its + // screenshots may carry test metadata too — but the journey users care + // about is the component (one step per story), not the runner's test. + const storyId = metadata?.story?.id; + if (storyId) { + const [component = storyId] = storyId.split("--"); + return { + key: `storybook › ${component}`, + prefix: "storybook", + title: component, + }; + } + const titlePath = metadata?.test?.titlePath + ?.map((segment) => segment.trim()) + .filter(Boolean); + if (titlePath && titlePath.length > 0) { + const title = titlePath.at(-1); + if (!title) { + return null; + } + return { + key: titlePath.join(" › "), + prefix: titlePath.slice(0, -1).join(" › "), + title, + }; + } + return null; +} + +/** Short display label for a step, from its key. */ +export function getStepLabel(stepKey: string): string { + return stepKey.split("/").pop() || stepKey; +} + +/** + * What is left of a screenshot name once its variant key is taken out: the + * browser prefix, the viewport suffix… — everything that tells one variant of + * a screen from another. Two screenshots of different steps with the same + * signature are the same variant of the journey, which is how the drawer and + * ⇧←/⇧→ stay on one viewport while moving between steps. + */ +export function getVariantSignature(screenshot: { + name: string; + variantKey: string; +}): string { + return screenshot.name.replace(screenshot.variantKey, ""); +} + +const LAST = Number.MAX_SAFE_INTEGER; + +/** + * Orders steps: capture order when the SDK recorded it, alphabetical by key + * otherwise. A step without an index sorts after those that have one. + */ +export function compareSteps( + a: { key: string; captureIndex: number | null }, + b: { key: string; captureIndex: number | null }, +): number { + return ( + (a.captureIndex ?? LAST) - (b.captureIndex ?? LAST) || + a.key.localeCompare(b.key) + ); +} + +export function getCaptureIndex(metadata: JourneyMetadata): number | null { + return metadata?.capture?.index ?? null; +} diff --git a/apps/frontend/src/pages/Build/metadata/testing.ts b/apps/frontend/src/pages/Build/metadata/testing.ts index b0e875a89..bc790a8e0 100644 --- a/apps/frontend/src/pages/Build/metadata/testing.ts +++ b/apps/frontend/src/pages/Build/metadata/testing.ts @@ -25,6 +25,7 @@ export function metadata(props: Partial): Metadata { latestVersion: null, }, story: null, + capture: null, viewport: null, test: null, tags: null, diff --git a/apps/frontend/src/pages/Build/sidebar/ScreenshotDiffThumbnail.tsx b/apps/frontend/src/pages/Build/sidebar/ScreenshotDiffThumbnail.tsx index 2e81129dd..cbe3c7d41 100644 --- a/apps/frontend/src/pages/Build/sidebar/ScreenshotDiffThumbnail.tsx +++ b/apps/frontend/src/pages/Build/sidebar/ScreenshotDiffThumbnail.tsx @@ -33,12 +33,15 @@ export function ScreenshotDiffThumbnail(props: { iconClassName?: string; /** How the image fills the box. */ fit?: "contain" | "cover"; + /** ImageKit transformations for the source, to match the box being drawn. */ + transformations?: string[]; }) { const { screenshotDiff, className, iconClassName = className, fit = "contain", + transformations = ["w-32", "h-32", "c-at_max"], } = props; const screenshot = screenshotDiff.compareScreenshot ?? screenshotDiff.baseScreenshot ?? null; @@ -57,7 +60,7 @@ export function ScreenshotDiffThumbnail(props: { > { + // Unknown keys are stripped, so a field the SDK sends and the schema does + // not declare is dropped on arrival without an error anywhere. + it("keeps the capture index", () => { + expect( + ScreenshotMetadataSchema.parse({ ...base, capture: { index: 3 } }) + .capture, + ).toEqual({ index: 3 }); + }); + + it("rejects a capture index that is not a position", () => { + expect( + ScreenshotMetadataSchema.safeParse({ ...base, capture: { index: -1 } }) + .success, + ).toBe(false); + expect( + ScreenshotMetadataSchema.safeParse({ ...base, capture: { index: 1.5 } }) + .success, + ).toBe(false); + }); + + it("accepts an SDK too old to record the capture index", () => { + expect(ScreenshotMetadataSchema.safeParse(base).success).toBe(true); + }); +}); diff --git a/packages/schemas/src/screenshot-metadata.ts b/packages/schemas/src/screenshot-metadata.ts index 3e6000e47..06fa7681b 100644 --- a/packages/schemas/src/screenshot-metadata.ts +++ b/packages/schemas/src/screenshot-metadata.ts @@ -129,6 +129,15 @@ const StoryMetadataSchema = z }) .meta({ description: "Storybook story metadata" }); +const CaptureSchema = z + .object({ + index: z.number().int().min(0).meta({ + description: + "The 0-based position of the screenshot within its test, following capture order", + }), + }) + .meta({ description: "How the screenshot was captured within its test" }); + export const ScreenshotMetadataSchema = z .object({ $schema: z @@ -162,6 +171,7 @@ export const ScreenshotMetadataSchema = z story: StoryMetadataSchema.nullish().meta({ description: "Storybook story metadata", }), + capture: CaptureSchema.nullish(), tags: z .array(z.string()) .optional() diff --git a/tests/build-journey.spec.ts b/tests/build-journey.spec.ts new file mode 100644 index 000000000..d50bdfda5 --- /dev/null +++ b/tests/build-journey.spec.ts @@ -0,0 +1,103 @@ +import { expect } from "@playwright/test"; + +import { createJourneyScenario } from "../apps/backend/src/database/seeds"; +import { loggedTest } from "./logged-test"; +import { ensureTeamOwner, screenshot } from "./util"; + +loggedTest( + "reviews a change against the journey it happened in", + async ({ page, auth, team, project }) => { + await ensureTeamOwner({ team: team.team, user: auth.user }); + const { build } = await createJourneyScenario({ projectId: project.id }); + + await page.goto( + `/${team.account.slug}/${project.name}/builds/${build.number}`, + ); + // The button is clickable before the diffs land, and then it has nothing + // to open: wait for the list. + await expect( + page.getByRole("button", { name: "checkout/confirmation.png" }), + ).toBeVisible(); + await page + .getByRole("button", { name: /^(Start review|Browse snapshots)/ }) + .click(); + + // The review opens on the biggest change, which is the last step of the + // purchase — so the journey is there to be opened, and its order is + // already known not to be the score's. + await expect( + page.getByRole("heading", { name: "checkout/confirmation.png" }), + ).toBeVisible(); + const toggle = page.getByRole("button", { name: "Journey" }); + await expect(toggle).toBeVisible(); + await toggle.click(); + + // The whole journey, in the order the test walked it — which is neither + // the alphabet (cart, confirmation, payment, shipping) nor the diff score + // (confirmation, payment). Cart and shipping did not change and are in it + // all the same: a change reads against the journey it happened in. + const drawer = page.getByTestId("journey-drawer"); + await expect(drawer.getByRole("button")).toHaveText([ + "1 · cart", + "2 · shipping", + "3 · payment", + "4 · confirmation", + ]); + + // The label is cut to fit, so it hands the whole key over on hover; the + // dot has no legend anywhere, so it explains itself. + // Base UI portals its tooltip out of the trigger and gives the box + // `role="presentation"`, so the portal is what there is to assert on. + const tooltip = page.locator("[data-base-ui-portal]"); + await expect(async () => { + await page.mouse.move(0, 0); + await drawer.getByText("2 · shipping").hover(); + await expect(tooltip).toHaveText("checkout/shipping", { timeout: 2_000 }); + }).toPass(); + await expect(async () => { + await page.mouse.move(0, 0); + await drawer.getByTestId("journey-step-attention").first().hover(); + await expect(tooltip).toHaveText("Needs review: Changed", { + timeout: 2_000, + }); + }).toPass(); + await page.mouse.move(0, 0); + + // Jumping to a step opens it, unchanged included. + await drawer.getByRole("button", { name: "1 · cart" }).click(); + await expect( + page.getByRole("heading", { name: "checkout/cart.png" }), + ).toBeVisible(); + await expect(drawer.locator("[aria-current='step']")).toHaveText( + "1 · cart", + ); + + // ⇧→ walks to the next step, ⇧← back — across status sections. + await page.keyboard.press("Shift+ArrowRight"); + await expect( + page.getByRole("heading", { name: "checkout/shipping.png" }), + ).toBeVisible(); + await page.keyboard.press("Shift+ArrowLeft"); + await expect( + page.getByRole("heading", { name: "checkout/cart.png" }), + ).toBeVisible(); + + await screenshot(page, "build-journey-drawer", { + replacements: { + [team.account.slug]: "acme", + }, + }); + + // A test that captures a single screen is regular visual testing, not a + // journey: nothing to open, and nothing offering to. + await page + .locator("[role='button'][data-index]") + .filter({ hasText: "account/settings.png" }) + .click(); + await expect( + page.getByRole("heading", { name: "account/settings.png" }), + ).toBeVisible(); + await expect(page.getByTestId("journey-drawer")).toHaveCount(0); + await expect(page.getByRole("button", { name: "Journey" })).toHaveCount(0); + }, +);