OceanFlow - AI Test Automation Platform

OceanFlow 由上海欧森智联网络科技有限公司（www.osenbot.com）提供技术支持。

OceanFlow is an agent-friendly automation plugin for Web, Desktop, and Mobile testing. It provides a REST API, stdio MCP server, CLI, and browser-based Web console for generating, running, and reviewing UI test scenarios.

Features

• Web automation tools for navigation, clicking, typing, extraction, visual assertions, performance, viewport, scrolling, and script execution.
• Desktop automation tools for click, type, and screenshot actions.
• Mobile automation tools for tap, swipe, and screenshot actions.
• AI-assisted scenario generation and BDD/Gherkin parsing.
• REST API with executable contract tests.
• WebSocket execution, browser, log, report, and skill events with session/channel filtering.
• Skill Store discovery, install, uninstall, enable, disable, search, and remote registry fetch support.
• Web console with modern TypeScript slices for projects, scenarios, execution, browser control, reports, Skill Store, and console assets, with modern-only startup.
• Project list management for active project context, branch selection, model selection, and scenario defaults.
• Screenshot capture, network request inspection/export/clear, and execution log filtering/export in the Web console.

Installation

npm install
npm run build

Quick Start

Run the AI command center API, Web UI, and WebSocket server together:

npm run build
npm run web

For local development, rebuild the Web bundle and restart the command center:

npm run dev

Service contracts:

• REST API: http://localhost:3335/api/health
• Web UI: http://localhost:3335
• MCP: stdio transport through node dist/mcp/server.js or oceanflow mcp

oceanflow mcp intentionally does not expose a port. --mcp-port is ignored for backward-compatible warnings because the MCP server uses StdioServerTransport.

Target Project Startup Fallback

When the AI command center starts an acceptance execution, the backend first makes sure the tested project itself is reachable before browser automation begins:

• POST /api/tasks/:id/execute verifies that the task has generated executable steps before it reports execution as started.
• The project runner installs or refreshes Node dependencies when node_modules is missing or older than the dependency manifests.
• If the configured/default port is already occupied, the runner chooses the next available port and starts the tested project there instead of treating an existing service as success.
• Startup attempts try the configured command, available package.json scripts (start, dev, preview), build + preview, framework fallbacks such as Vite/Next, and a static HTTP fallback for projects with an index.html.
• Vite commands use --strictPort so the reported health URL always matches the actual tested-project service.
• If Midscene or the vision model is unavailable, execution automatically falls back to the standard Playwright browser engine so steps, screenshots, logs, and reports are still produced.
• Generated multi-scenario flows are isolated: cookies, localStorage, and sessionStorage are cleared before each new scenario to avoid login/token state leaking into negative or route-guard checks.

For full AI-powered visual execution, configure OCEANFLOW_VISION_API_KEY, OCEANFLOW_VISION_MODEL, and OCEANFLOW_VISION_BASE_URL in .env. Without them, the fallback browser engine can still run against the started tested project and generate evidence.

Web Development

npm run web:typecheck
npm run web:build
npm run web:check
npm run web:smoke
npm run web

Modern Web source lives in web/src and compiles to web/dist/main.js. web/index.html imports the modern runtime directly and shows a modern-runtime error banner if initialization fails.

Modern slices are split by responsibility:

• web/src/features/scenarios.ts plus web/src/features/scenarios/*: scenario loading, AI generation, response extraction, local fallback, rendering, and API persistence.
• web/src/features/projects.ts: REST-backed project registry orchestration, active project context, import/export, repository sync, and local fallback transitions.
• web/src/features/projects/model.ts and web/src/features/projects/render.ts: project state normalization, offline import fallback, branch/model selection, project summary rendering, and scenario defaults.
• web/src/features/execution.ts plus web/src/features/execution/*: run/stop actions, WebSocket event filtering, active scenario ownership, step updates, report rendering, and execution logs.
• web/src/features/browser.ts plus web/src/features/browser/model.ts: browser navigation feedback and response normalization.
• web/src/features/console-assets.ts plus web/src/features/console-assets/*: screenshot capture/view/export, network filtering/details/export/clear, log filtering/export, and shared console asset model helpers.
• web/src/features/reports.ts plus web/src/features/reports/*: report list loading, response normalization, statistics fallback, and rendering.
• web/src/features/skills.ts plus web/src/features/skills/*: installed Skill Store, remote registry views, response normalization, display labels, and rendering.
• web/src/features/ai.ts plus web/src/features/ai/model.ts: AI chat submission and response formatting.

Runtime markers:

window.HARNESS_WEB_ENTRY
window.__HARNESS_WEB_READY__

Verification

npm run build
npm run typecheck
npm run lint
npm test
npm run web:check
npm run web:smoke

npm test includes unit and integration-level contract tests for:

• tool registry completeness
• MCP tool contract
• REST API endpoint contracts
• Web runtime bootstrap and panel shell
• WebSocket session/channel filtering
• Skill Store remote registry behavior
• API/TestExecutor execution consistency
• Session runtime isolation

API Contracts

Executable API contracts are defined in src/api/contracts.ts and verified by src/api/__tests__/contracts.test.ts. Human-readable details are in docs/api-contracts.md.

Web Acceptance

Manual and automated Web acceptance steps are documented in docs/WEB_ACCEPTANCE_CHECKLIST.md. The modern Web runtime is the only startup path and initializeHarnessWeb() is idempotent, so repeated startup calls do not duplicate feature registrations.

CLI

npx @osenai/oceanflow web --port 3335
npx @osenai/oceanflow api --api-port 3335
npx @osenai/oceanflow mcp
npx @osenai/oceanflow create "User Login Flow"
npx @osenai/oceanflow run scenario-123
npx @osenai/oceanflow report scenario-123
npx @osenai/oceanflow list

License

MIT

Web smoke test: npm run web:smoke starts an isolated static server for web/, launches Playwright Chromium with mock REST/WebSocket services, and verifies modern runtime readiness plus API-backed feature interactions.