feat(agentflow): enhance validation and feedback mechanisms (#5915)

* feat(agentflow): enhance validation and feedback mechanisms

- Added constraint validation functions to ensure flow integrity, including checks for single start nodes, nested iterations, and human input restrictions within iterations.
- Implemented a new ValidationFeedback component to display validation results and issues directly in the UI.
- Updated the Agentflow component to integrate validation feedback and display snackbar notifications for constraint violations.
- Enhanced flow validation logic to detect hanging edges and validate node inputs, improving overall flow integrity checks.
- Introduced new test cases for validation functions to ensure robustness and reliability.

* address gemini review feedback

Author: jocelynlin-wd

packages/agentflow/TESTS.md

@@ -1,137 +1,112 @@
-# @flowiseai/agentflow Test Plan
+# @flowiseai/agentflow — Testing Guide
 
 ## Running Tests
 
 ```bash
-# Fast run (no coverage)
-pnpm test
+pnpm test              # Fast run (no coverage)
+pnpm test:coverage     # With coverage enforcement
+pnpm test:watch        # Watch mode during development
+```
 
-# With coverage enforcement
-pnpm test:coverage
+## Test Strategy
 
-# Watch mode during development
-pnpm test:watch
-```
+Tests are prioritized by impact. When modifying a file, add or update tests in the same PR.
 
-## Test Coverage by Tier
+### Tier 1 — Core Logic (must test)
 
-Add tests when actively working on these files. Each tier reflects impact and testability.
+Pure business logic in `core/`, `infrastructure/`, and critical hooks. These carry the highest risk — a bug here affects every user. Always test in the same PR when modifying.
 
-### Tier 1 — Core Logic
+**What belongs here:** validation rules, node utilities, API clients, state management (reducers, context actions), flow data hooks (`useFlowHandlers`).
 
-These modules carry the highest risk. Test in the same PR when modifying.
+### Tier 2 — Feature Hooks & Dialogs (test when changing)
 
-<!-- prettier-ignore -->
-| File | Key exports to test | Status |
-| --- | --- | --- |
-| `src/core/validation/` | `validateFlow`, `validateNode` — empty flows, missing/multiple starts, disconnected nodes, cycles, required inputs; `isValidConnectionAgentflowV2` — self-connections, cycle detection | ✅ Done |
-| `src/core/utils/` | `getUniqueNodeId`, `getUniqueNodeLabel`, `initNode`, `generateExportFlowData` | ✅ Done |
-| `src/core/node-catalog/` | `filterNodesByComponents`, `isAgentflowNode`, `groupNodesByCategory` | ✅ Done |
-| `src/core/node-config/` | `getAgentflowIcon`, `getNodeColor` | ✅ Done |
-| `src/core/theme/tokens.ts` | All design tokens — node colors, light/dark variants, spacing scale, semantic colors, ReactFlow colors, shadows, border radius, gradients | ✅ Done |
-| `src/core/theme/cssVariables.ts` | `generateCSSVariables()` — valid CSS strings, all variables, correct light/dark values, proper formatting, consistency with tokens | ✅ Done |
-| `src/core/theme/createAgentflowTheme.ts` | `createAgentflowTheme()` — MUI theme creation, palette mode, colors from tokens, custom card palette, spacing, border radius, consistency | ✅ Done |
-| `src/infrastructure/api/client.ts` | `createApiClient` — headers, auth token, 401 interceptor | ✅ Done |
-| `src/infrastructure/api/chatflows.ts` | All CRUD + `generateAgentflow` + `getChatModels`, FlowData serialization | ✅ Done |
-| `src/infrastructure/api/nodes.ts` | `getAllNodes`, `getNodeByName`, `getNodeIconUrl` | ✅ Done |
-| `src/infrastructure/store/AgentflowContext.tsx` | `agentflowReducer` (all actions), `normalizeNodes`, `deleteNode()`, `duplicateNode()`, `openEditDialog()`, `closeEditDialog()`, `setNodes()`, `setEdges()`, `updateNodeData()`, `deleteEdge()`, state synchronization with local setters. E2E: composite workflow (add→connect→edit→save), load→modify→save roundtrip, multi-edge from single node, rapid connect/disconnect cycles, edge deletion | ✅ Done |
-| `src/infrastructure/store/ApiContext.tsx` | `ApiProvider` — client creation, memoization, `useApiContext` error boundary | ✅ Done |
-| `src/useAgentflow.ts` | `getFlow()`, `toJSON()`, `validate()`, `addNode()`, `clear()`, `fitView()`, `getReactFlowInstance()`, instance stability | ✅ Done |
-| `src/features/canvas/hooks/useFlowHandlers.ts` | `handleConnect`, `handleNodesChange`, `handleEdgesChange`, `handleAddNode` — synchronous `onFlowChange` callbacks, dirty tracking, viewport resolution, change filtering | ✅ Done |
+Feature-level hooks and dialog components that orchestrate UI behavior. Test when adding features or fixing bugs.
 
-### Tier 2 — Feature Hooks & Dialogs
+**What belongs here:** search logic, drag-and-drop, node color calculations, dialog state machines, theme detection.
 
-Test when adding features or fixing bugs in these areas.
+### Tier 3 — UI Components (test if logic exists)
 
-<!-- prettier-ignore -->
-| File | Key exports to test | Status |
-| --- | --- | --- |
-| `src/features/node-palette/search.ts` | `fuzzyScore`, `searchNodes`, `debounce` | ✅ Done |
-| `src/features/canvas/hooks/useFlowNodes.ts` | `useFlowNodes()` — category filtering, component whitelist, error states | ✅ Done |
-| `src/features/canvas/hooks/useDragAndDrop.ts` | `useDragAndDrop()` — JSON parse error handling, node init on drop | ✅ Done |
-| `src/features/canvas/hooks/useNodeColors.ts` | `useNodeColors()` — color calculations for selected/hover/dark mode | ✅ Done |
-| `src/infrastructure/store/ConfigContext.tsx` | `ConfigProvider` — theme detection (light/dark/system), media query listener | ✅ Done |
-| `src/features/generator/GenerateFlowDialog.tsx` | Dialog state machine — API call flow, error handling, progress state | ✅ Done |
-| `src/features/node-editor/EditNodeDialog.tsx` | Label editing — keyboard handling (Enter/Escape), node data updates | ✅ Done |
-| `src/features/canvas/hooks/useOpenNodeEditor.ts` | `openNodeEditor()` — node/schema lookup, inputValues initialization, early returns, fallback to `node.data.inputs` when API schema unavailable, API schema priority over `data.inputs` | ✅ Done |
+Presentational components that are mostly JSX. Only add tests if the component contains meaningful business logic (e.g., an exported helper function). Pure styling components (`styled.ts`, `MainCard.tsx`, etc.) do not need tests.
 
-### Tier 3 — UI Components
+## Writing Tests
 
-Mostly JSX with minimal logic. Only add tests if business logic is introduced.
+### File Extension Convention
 
-<!-- prettier-ignore -->
-| File | Key exports to test | Status |
-| --- | --- | --- |
-| `src/features/canvas/components/NodeOutputHandles.tsx` | `getMinimumNodeHeight()` — linear scaling, MIN_NODE_HEIGHT floor | ✅ Done |
-| `src/features/canvas/components/ConnectionLine.tsx` | Edge label visibility per node type, label content (condition index, humanInput proceed/reject), edge color from AGENTFLOW_ICONS | ✅ Done |
-| `src/Agentflow.tsx` | Integration test — dark mode, ThemeProvider, CSS variables, header rendering, keyboard shortcuts (Cmd+S / Ctrl+S save), generate flow dialog, imperative ref | ✅ Done |
+The Jest config uses file extensions to select the test environment:
 
-Files that are pure styling or data constants (`styled.ts`, `nodeIcons.ts`, `MainCard.tsx`, etc.) do not need dedicated tests.
+| Extension   | Environment             | When to use                                                                |
+| ----------- | ----------------------- | -------------------------------------------------------------------------- |
+| `.test.ts`  | **node** (no DOM)       | Pure logic — utilities, reducers, data transformations                     |
+| `.test.tsx` | **jsdom** (browser DOM) | Anything that renders React — `renderHook` with providers, component tests |
 
-## Test Utilities
+Source files use `.tsx` only when they contain JSX syntax. A hook like `useAgentflow.ts` has no JSX, so it stays `.ts` even though its test is `.test.tsx` (because the test uses `renderHook` with a JSX wrapper).
 
-### Factory Functions (`src/__test_utils__/factories.ts`)
+### Factory Functions
 
-Use factory functions to create test fixtures with sensible defaults:
+Use factory functions from `@test-utils/factories` to create test fixtures with sensible defaults:
 
 ```typescript
 import { makeFlowNode, makeFlowEdge, makeNodeData } from '@test-utils/factories'
 
-// Create test nodes
 const node = makeFlowNode('node-1', {
     type: 'agentflowNode',
     data: { name: 'llmAgentflow', label: 'LLM' }
 })
 
-// Create test edges
 const edge = makeFlowEdge('node-1', 'node-2')
 
-// Create node data (for palette/search tests)
 const nodeData = makeNodeData({ name: 'llmAgentflow', label: 'LLM' })
 ```
 
-### Custom Jest Environment
-
-**File**: `src/__test_utils__/jest-environment-jsdom.js`
+### Mocking Patterns
 
-Prevents the `canvas` native module from being loaded during jsdom initialization. The canvas package requires native compilation which fails in many environments, but it's only an optional dependency of jsdom and not needed for React component tests.
+**Mocking a module with `jest.mock`:**
 
-This custom environment intercepts `require('canvas')` at the module level and returns a mock before jsdom tries to load the native binary.
+```typescript
+import { isValidConnectionAgentflowV2 } from '@/core'
 
-### Module Mocks
+jest.mock('@/core', () => ({
+    isValidConnectionAgentflowV2: jest.fn(() => true),
+    getUniqueNodeId: jest.fn(() => 'new-node-1')
+}))
 
-**ReactFlow Mock** (`src/__mocks__/reactflow.tsx`): Provides mock implementations of ReactFlow components and hooks.
+// Override per-test:
+it('should reject invalid connection', () => {
+    ;(isValidConnectionAgentflowV2 as jest.Mock).mockReturnValueOnce(false)
+    // ...
+})
+```
 
-Key features:
+**Mocking context hooks:**
 
--   Uses `forwardRef` for MUI `styled()` compatibility (prevents emotion errors)
--   Uses `useState` internally to maintain stable references (prevents infinite re-render loops)
--   Exports all commonly used ReactFlow components (`Controls`, `MiniMap`, `Background`, etc.)
--   Mocks hooks (`useNodesState`, `useEdgesState`, `useReactFlow`)
+```typescript
+const mockSetDirty = jest.fn()
+
+jest.mock('@/infrastructure/store', () => ({
+    useAgentflowContext: () => ({
+        state: { reactFlowInstance: null },
+        setDirty: mockSetDirty
+    })
+}))
+```
 
-**Axios Mock** (`src/__mocks__/axios.ts`): Prevents network errors by mocking all HTTP requests. Returns empty arrays/objects for all API calls to silence network warnings in tests.
+### Module Mocks
 
-**CSS Mock** (`src/__mocks__/styleMock.js`): Empty object export for CSS imports.
+**ReactFlow** (`src/__mocks__/reactflow.tsx`): Mock implementations of ReactFlow components and hooks. Uses `forwardRef` for MUI `styled()` compatibility and `useState` internally for stable references.
 
-## File Extension Convention
+**Axios** (`src/__mocks__/axios.ts`): Prevents network errors by mocking all HTTP methods. Returns empty arrays/objects by default.
 
-The jest config uses file extensions to select the test environment:
+**CSS/SVG** (`src/__mocks__/styleMock.js`): Empty object export for CSS and SVG imports.
 
-| Extension   | Environment             | When to use                                                                |
-| ----------- | ----------------------- | -------------------------------------------------------------------------- |
-| `.test.ts`  | **node** (no DOM)       | Pure logic — utilities, reducers, data transformations                     |
-| `.test.tsx` | **jsdom** (browser DOM) | Anything that renders React — `renderHook` with providers, component tests |
+### Custom Jest Environment
 
-**Source files** follow a different rule: use `.tsx` only when the file contains JSX syntax. A React hook like `useAgentflow.ts` has no JSX, so it stays `.ts` even though its test file is `.test.tsx` (because the test uses `renderHook` with a JSX wrapper).
+`src/__test_utils__/jest-environment-jsdom.js` intercepts `require('canvas')` and returns a mock before jsdom tries to load the native binary. This prevents build failures in environments without native canvas compilation.
 
 ## Configuration
 
 -   **Jest config**: `jest.config.js` — two projects: `unit` (node env, `.test.ts`) and `components` (custom jsdom env, `.test.tsx`)
--   **Test environment**: Component tests use custom jsdom environment (`src/__test_utils__/jest-environment-jsdom.js`) to handle canvas loading
--   **Import aliases**: `@test-utils` maps to `src/__test_utils__` for convenient imports
--   **Coverage thresholds**: uniform 80% floor (`branches`, `functions`, `lines`, `statements`) — see `coverageThreshold` in `jest.config.js` for the full list
--   **Coverage exclusions**:
-    -   `src/__test_utils__/**` — test utilities
-    -   `src/__mocks__/**` — module mocks
+-   **Import aliases**: `@test-utils` maps to `src/__test_utils__`, `@/` maps to `src/`
+-   **Coverage thresholds**: 80% floor for `branches`, `functions`, `lines`, `statements` — see `coverageThreshold` in `jest.config.js` for per-path entries
+-   **Coverage exclusions**: `src/__test_utils__/**`, `src/__mocks__/**`
 -   **CI**: `pnpm test:coverage` runs in GitHub Actions between lint and build
 -   **Reports**: `coverage/lcov-report/index.html` for detailed HTML report

packages/agentflow/jest.config.js

@@ -13,6 +13,7 @@ const baseConfig = {
     testPathIgnorePatterns: ['/node_modules/', '/dist/'],
     moduleNameMapper: {
         '^@test-utils/(.*)$': '<rootDir>/src/__test_utils__/$1',
+        '\\.svg$': '<rootDir>/src/__mocks__/styleMock.js',
         '^@/(.*)$': '<rootDir>/src/$1',
         '\\.(css|less|scss|sass)$': '<rootDir>/src/__mocks__/styleMock.js'
     }

packages/agentflow/src/Agentflow.tsx

@@ -1,10 +1,12 @@
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react'
 import ReactFlow, { Background, Controls, MiniMap, ReactFlowProvider, useEdgesState, useNodesState } from 'reactflow'
 
+import { Alert, Snackbar } from '@mui/material'
 import { IconSparkles } from '@tabler/icons-react'
 
 import { tokens } from './core/theme'
 import type { AgentFlowInstance, AgentflowProps, FlowData, FlowDataCallback, FlowEdge, FlowNode } from './core/types'
+import { applyValidationErrorsToNodes, validateFlow } from './core/validation'
 import {
     AgentflowHeader,
     ConnectionLine,
@@ -15,6 +17,7 @@ import {
     useFlowHandlers,
     useFlowNodes
 } from './features/canvas'
+import { ValidationFeedback } from './features/canvas/components'
 import { GenerateFlowDialog } from './features/generator'
 import { EditNodeDialog } from './features/node-editor'
 import { AddNodesDrawer, StyledFab } from './features/node-palette'
@@ -80,6 +83,17 @@ function AgentflowCanvas({
     const [edges, setLocalEdges, onEdgesChange] = useEdgesState(initialFlow?.edges || [])
     const [showGenerateDialog, setShowGenerateDialog] = useState(false)
 
+    // Constraint violation snackbar state
+    const [snackbar, setSnackbar] = useState<{ open: boolean; message: string }>({ open: false, message: '' })
+
+    const handleConstraintViolation = useCallback((message: string) => {
+        setSnackbar({ open: true, message })
+    }, [])
+
+    const handleSnackbarClose = useCallback(() => {
+        setSnackbar({ open: false, message: '' })
+    }, [])
+
     // Load available nodes
     const { availableNodes } = useFlowNodes()
 
@@ -106,14 +120,16 @@ function AgentflowCanvas({
         onNodesChange,
         onEdgesChange,
         onFlowChange,
-        availableNodes
+        availableNodes,
+        onConstraintViolation: handleConstraintViolation
     })
 
     // Drag and drop handlers
     const { handleDragOver, handleDrop } = useDragAndDrop({
         nodes: nodes as FlowNode[],
         setLocalNodes: setLocalNodes as React.Dispatch<React.SetStateAction<FlowNode[]>>,
-        reactFlowWrapper: reactFlowWrapper as React.RefObject<HTMLDivElement>
+        reactFlowWrapper: reactFlowWrapper as React.RefObject<HTMLDivElement>,
+        onConstraintViolation: handleConstraintViolation
     })
 
     // Handle generated flow from dialog
@@ -134,13 +150,25 @@ function AgentflowCanvas({
         [setLocalNodes, setLocalEdges, setDirty, onFlowGenerated]
     )
 
-    // Handle save
+    // Handle save — run validation first and highlight problem nodes
     const handleSave = useCallback(() => {
-        if (onSave) {
-            onSave(agentflow.getFlow())
-            setDirty(false)
+        if (!onSave) return
+
+        const flowNodes = nodes as FlowNode[]
+        const flowEdges = edges as FlowEdge[]
+        const result = validateFlow(flowNodes, flowEdges, availableNodes)
+
+        // Update node border highlighting: set errors on failing nodes, clear errors on now-valid nodes
+        setLocalNodes((prev) => applyValidationErrorsToNodes(prev as FlowNode[], result.errors) as FlowNode[])
+
+        if (!result.valid) {
+            handleConstraintViolation('Flow has validation errors. Please fix them before saving.')
+            return
         }
-    }, [onSave, agentflow, setDirty])
+
+        onSave(agentflow.getFlow())
+        setDirty(false)
+    }, [onSave, agentflow, setDirty, nodes, edges, availableNodes, setLocalNodes, handleConstraintViolation])
 
     // Keyboard shortcut: Cmd+S / Ctrl+S to save
     useEffect(() => {
@@ -210,6 +238,16 @@ function AgentflowCanvas({
                         </StyledFab>
                     )}
 
+                    {/* Validation Feedback - positioned at top right */}
+                    {!readOnly && (
+                        <ValidationFeedback
+                            nodes={nodes as FlowNode[]}
+                            edges={edges as FlowEdge[]}
+                            availableNodes={availableNodes}
+                            setNodes={setLocalNodes as React.Dispatch<React.SetStateAction<FlowNode[]>>}
+                        />
+                    )}
+
                     <ReactFlow
                         nodes={nodes}
                         edges={edges}
@@ -244,6 +282,18 @@ function AgentflowCanvas({
 
             {/* Edit Node Dialog */}
             <EditNodeDialog show={state.editingNodeId !== null} dialogProps={state.editDialogProps || {}} onCancel={closeEditDialog} />
+
+            {/* Constraint Violation Snackbar */}
+            <Snackbar
+                open={snackbar.open}
+                autoHideDuration={5000}
+                onClose={handleSnackbarClose}
+                anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
+            >
+                <Alert onClose={handleSnackbarClose} severity='error' variant='filled' sx={{ width: '100%' }}>
+                    {snackbar.message}
+                </Alert>
+            </Snackbar>
         </div>
     )
 }