Secondary text

Hoverable area

``` Section layout primitives from `@agenta/ui`: ```typescript import { SectionCard, SectionLabel, SectionHeaderRow, ConfigBlock, VersionBadge, RevisionLabel, StatusTag, PanelHeader, SourceIndicator, } from "@agenta/ui" Configuration} right={} /> ``` ## Package selection guide ```text Need a primitive (button, dialog, ...)? → @agenta/ui/ui Need a modal? → Dialog from @agenta/ui/ui (EnhancedModal for antd-style call sites) Class-name utils or theme colors? → cn, textColors, bgColors from @agenta/ui Section layout primitives? → SectionCard, SectionLabel, ConfigBlock from @agenta/ui Entity state management (molecules)? → *Molecule from @agenta/entities/{entity} Entity selection UI? → EntityPicker from @agenta/entity-ui/selection Loadable bridge? → loadableBridge from @agenta/entities/loadable Building playground features? → state from @agenta/playground, UI from @agenta/playground-ui Chat, sessions, observability, ...? → the domain's headless + -ui package pair ``` ## Molecule pattern (entity state management) Full documentation: `web/packages/agenta-entities/src/shared/README.md`. A molecule provides a unified API for entity state with draft, loading, and cache: ```typescript molecule.atoms.* // atom families for reactive subscriptions molecule.reducers.* // write operations molecule.get.* / set.* // imperative reads/writes (snapshot from store) molecule.useController // React hook combining atoms + dispatch molecule.cleanup.* // memory management ``` Where to use which API: ```text React component → useAtom / molecule.useController Inside an atom → get(molecule.atoms.*) Callback/effect → molecule.get.* / molecule.set.* ``` ```typescript import {testcaseMolecule} from "@agenta/entities/testcase" function TestcaseEditor({id}: {id: string}) { const [state, dispatch] = testcaseMolecule.useController(id) if (state.isPending) return if (!state.data) return return dispatch.update({input: e.target.value})} /> } // Fine-grained subscription: only re-renders when isDirty changes function DirtyIndicator({id}: {id: string}) { const isDirty = useAtomValue(testcaseMolecule.atoms.isDirty(id)) return isDirty ? Modified : null } ``` Imperative API for callbacks: ```typescript async function handleSave(id: string) { const data = testcaseMolecule.get.data(id) if (!data || !testcaseMolecule.get.isDirty(id)) return await api.save(data) testcaseMolecule.set.discard(id) } ``` Examples: `workflowMolecule` (`@agenta/entities/workflow`), `testcaseMolecule` (`@agenta/entities/testcase`), `traceSpanMolecule` (`@agenta/entities/trace`), `testsetMolecule` and `revisionMolecule` (`@agenta/entities/testset`). Other entity subpaths (`session`, `secret`, `gatewayTool`, ...) follow the same pattern. Data flow: `Server → TanStack Query → atoms.serverData → atoms.draft (local changes) → atoms.data (merged) → useController → component`. Anti-patterns: ```typescript // BAD - atoms require React context async function handleSave(id) { const data = useAtomValue(molecule.atoms.data(id)) } // breaks // GOOD - imperative API async function handleSave(id) { const data = molecule.get.data(id) } // BAD - new atom every render const derived = atom((get) => get(molecule.atoms.data(id))) // GOOD - memoize the atom const derived = useMemo(() => atom((get) => get(molecule.atoms.data(id))), [id]) ``` ## Loadable bridge pattern Full documentation: `web/packages/agenta-entities/src/loadable/README.md`. A loadable represents a data source that provides input rows (local mode = manual entry, connected mode = synced with a testset revision or trace). ```typescript import {loadableBridge} from "@agenta/entities/loadable" import {useAtomValue, useSetAtom} from "jotai" const rows = useAtomValue(loadableBridge.selectors.rows(loadableId)) const addRow = useSetAtom(loadableBridge.actions.addRow) addRow(loadableId, {prompt: "Hello, world!"}) const connect = useSetAtom(loadableBridge.actions.connectToSource) connect(loadableId, testsetRevisionId, "MyTestset v1", "testcase") ``` Selectors: `rows`, `columns`, `activeRow`, `mode`, `isDirty`, `connectedSource`. Actions: `addRow`, `updateRow`, `removeRow`, `setActiveRow`, `connectToSource`, `disconnect`. ## Runnables (executable entities) Full documentation: `web/packages/agenta-entities/src/runnable/README.md`. A runnable is an executable entity (app, evaluator, or agent revision). There is no separate runnable bridge: read revision data straight from `workflowMolecule`. `@agenta/entities/runnable` holds the execution utilities and port helpers. ```typescript import {workflowMolecule} from "@agenta/entities/workflow" import {useAtomValue} from "jotai" const data = useAtomValue(workflowMolecule.selectors.data(revisionId)) const inputPorts = useAtomValue(workflowMolecule.selectors.inputPorts(revisionId)) const outputPorts = useAtomValue(workflowMolecule.selectors.outputPorts(revisionId)) const config = useAtomValue(workflowMolecule.selectors.configuration(revisionId)) ``` ## Entity selection system Full documentation: `web/packages/agenta-entity-ui/src/selection/README.md`. Use the unified `EntityPicker` from `@agenta/entity-ui/selection` for hierarchical selection (Workflow → Variant → Revision). ```typescript import { EntityPicker, type TestsetSelectionResult, type WorkflowRevisionSelectionResult, } from "@agenta/entity-ui/selection" // Cascading dropdowns (inline forms, compact) variant="cascading" adapter="workflowRevision" onSelect={handleSelect} /> // Breadcrumb navigation (modals) variant="breadcrumb" adapter="workflowRevision" onSelect={handleSelect} showSearch showBreadcrumb rootLabel="All Apps" /> // List with hover popovers (sidebars, 2-level) variant="list-popover" adapter="testset" onSelect={handleSelect} autoSelectLatest selectLatestOnParentClick /> ``` Mode hooks: `useCascadingMode`, `useBreadcrumbMode`, `useListPopoverMode`. Pre-built adapters: | Adapter | Hierarchy | Selection result | | --- | --- | --- | | `workflowRevision` | Workflow → Variant → Revision (filter apps/evaluators with query flags; `createWorkflowRevisionAdapter` for a 2-level variant) | `WorkflowRevisionSelectionResult` | | `evaluator` | Flat evaluator list | `EvaluatorSelectionResult` | | `testset` | Testset → Revision | `TestsetSelectionResult` | ## Package unit tests Packages host tests under `tests/unit/`, not in `src/`. Most packages run vitest (each has a `vitest.config.ts` at its root). Any new package shipping testable logic should match this layout. ### Layout ```text web/packages// ├── package.json # vitest + scripts ├── tsconfig.json # excludes src/**/__tests__/** ├── vitest.config.ts # at package root └── tests/ ├── __mocks__/ # stub deps (e.g. @agenta/ui for antd) └── unit/ └── .test.ts ``` Why tests live in `tests/unit/`, not `src/`: the package build runs `tsc --noEmit` over `src/`. Test files in `src/**/__tests__/**` pull in deps not declared in the package's `dependencies`, which CI's stricter resolution fails on even though they resolve locally via hoisting. Test runners transpile independently of the package `tsconfig`, so moving tests out of `src/` does not change how they run. Reference: commit `1c0a900`. ### Minimal vitest.config.ts ```typescript import {defineConfig} from "vitest/config" export default defineConfig({ test: { include: ["tests/unit/**/*.test.ts"], environment: "node", reporters: ["default", "junit"], outputFile: {junit: "./test-results/junit.xml"}, coverage: { provider: "v8", include: ["src/**/*.ts"], exclude: ["src/**/index.ts"], reporter: ["text", "lcov", "json-summary"], reportsDirectory: "./coverage", }, }, }) ``` For packages that import React/antd, stub `@agenta/ui` to keep the test env pure Node: ```typescript resolve: { alias: {"@agenta/ui": path.resolve(__dirname, "tests/__mocks__/agenta-ui.ts")}, }, ``` ### Standard package.json scripts ```json { "scripts": { "test": "pnpm run test:unit", "test:unit": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", "check": "pnpm run types:check && pnpm run lint" }, "devDependencies": { "@vitest/coverage-v8": "^4.1.4", "vitest": "^4.1.4" } } ``` ### Mocking the Fern client in tests Mock `@agenta/sdk/resources` (the per-resource accessors), not axios. Constructing a real Fern client reads env vars and initializes transport, neither of which a unit test wants. ```typescript import {beforeEach, describe, expect, it, vi} from "vitest" const fernRetrieve = vi.fn() vi.mock("@agenta/sdk/resources", () => ({ getWorkflowsClient: () => ({retrieveWorkflowRevision: fernRetrieve}), })) // Import the unit-under-test AFTER vi.mock so it picks up the mocked module. import {retrieveWorkflowRevision} from "../../src/workflow/api/api" beforeEach(() => { fernRetrieve.mockReset() }) it("invokes the Fern client with project_id as a queryParam", async () => { fernRetrieve.mockResolvedValueOnce({workflow_revision: {id: "rev-1"}}) await retrieveWorkflowRevision({projectId: "proj-42", workflowRef: {id: "wf-1"}}) const [body, opts] = fernRetrieve.mock.calls[0] expect(body).toEqual({workflow_ref: {id: "wf-1"}}) expect(opts).toEqual({queryParams: {project_id: "proj-42"}}) }) ``` Reference test files: - `web/packages/agenta-entities/tests/unit/retrieveWorkflowRevision.test.ts` (Fern mocked) - `web/packages/agenta-playground/tests/unit/traceRefResolution.test.ts` (pure logic) - `web/packages/agenta-entities/tests/__mocks__/agenta-ui.ts` (antd stub) ### Integration tests For code that exercises a real backend, use a separate `vitest.integration.config.ts` with `include: ["tests/integration/**/*.test.ts"]`, raised timeouts (30s), `sequence.concurrent: false`, and `globalSetup` + `setupFiles`. No coverage section. `@agenta/entities` is the established example (`web/packages/agenta-entities/vitest.integration.config.ts`). Write an integration test (not a unit test) when: the code talks to a real backend and the request/response contract is the thing under test; the code coordinates multiple molecules/atoms whose interaction is the bug surface; or you are testing a migration path where the real backend behaviour is the spec. Otherwise use a unit test. ### What to test High value: API request shape (correct Fern method, body, query params), boundary validation (bad responses return `null`/empty instead of crashing), pure derivation logic (extractors, predicates, key-priority pickers, cache TTL), and guards (empty IDs, missing project IDs). Skip: anything needing a running React tree, HTTP transport (Fern owns it), and antd rendering inside packages.