{
  "markdown": "# TestMesh\n\n> **A platform for writing and running end-to-end integration tests**\n\nTestMesh makes it easy to write, manage, and execute integration tests across multiple protocols. Define tests in YAML, run them locally or in CI/CD, and get detailed execution results.\n\n## Installation\n\n**curl (Linux/macOS)**\n```sh\ncurl -fsSL https://testmesh.io/install.sh | sh\n```\n\n**Homebrew (macOS/Linux)**\n```sh\nbrew install test-mesh/brew/testmesh\n```\n\n**npm / npx**\n```sh\nnpx -y @testmesh/cli --version\n# or install globally\nnpm install -g @testmesh/cli\n```\n\n**go install**\n```sh\ngo install github.com/test-mesh/testmesh/cli@latest\n```\n\n### MCP Server (for AI assistants)\n\nAdd to your `.mcp.json` or Claude/Cursor config:\n\n```json\n{\n  \"mcpServers\": {\n    \"testmesh\": {\n      \"command\": \"testmesh\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr with npx (zero install):\n```json\n{\n  \"mcpServers\": {\n    \"testmesh\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@testmesh/cli\", \"mcp\"]\n    }\n  }\n}\n```\n\n## Repository Structure\n\nThis is a monorepo containing all TestMesh components:\n\n```\ntestmesh/\n├── api/          # Go backend service (modular monolith)\n├── cli/          # CLI tool for running flows locally\n├── dashboard/    # Next.js frontend dashboard (port 3000)\n├── web/          # Documentation site (port 3001)\n├── services/     # Demo microservices for testing\n│   ├── user-service/\n│   ├── product-service/\n│   ├── order-service/\n│   └── notification-service/\n├── examples/     # Example test flows\n└── docs/         # Architecture & feature documentation\n```\n\n## Why TestMesh?\n\n### 🎯 Simple & Powerful\nWrite tests in human-readable YAML. No complex coding required. Yet powerful enough to handle complex scenarios with data extraction, assertions, and variable passing between steps.\n\n### 🔌 Multi-Protocol Support\n- **HTTP/REST APIs** - Full HTTP client with headers, auth, assertions\n- **Databases** - PostgreSQL, MySQL query execution and validation\n- **Message Queues** - Kafka producer/consumer testing\n- **Redis** - GET/SET operations, caching verification\n- **WebSocket** - Real-time communication testing\n\n### 🧪 Demo Microservices\nIncludes a complete e-commerce microservices architecture for demonstration:\n- **User Service** - User management with Redis sessions\n- **Product Service** - Product catalog with Redis caching and inventory locking\n- **Order Service** - Order processing with inter-service HTTP calls\n- **Notification Service** - Event-driven notifications via Kafka\n\nPerfect for learning integration testing patterns and demonstrating TestMesh capabilities.\n\n### 💻 Developer Experience\n- **CLI tool** for local development and CI/CD\n- **YAML-based** test definitions\n- **Variable extraction** from responses (JSONPath)\n- **Assertions** with expression language\n- **Real-time dashboard** for monitoring\n\n## Quick Start\n\n### Prerequisites\n\nTestMesh requires:\n- **PostgreSQL** (5432) - for data persistence\n- **Redis** (6379) - for caching and job queue\n- **Kafka** (9092) - optional, for async testing\n\n**Option A**: Use your existing services\n**Option B**: Use our bundled services (see below)\n\n### Option A: Using Existing Infrastructure\n\nIf you already have PostgreSQL, Redis, and Kafka running:\n\n```bash\n# 1. Configure connection details\ncp .env.example .env\n# Edit .env with your database/redis/kafka connection details\n\n# 2. Start TestMesh\ndocker-compose up -d\n\n# 3. Access the dashboard\nopen http://localhost:3000\n```\n\n### Option B: Full Local Development Setup\n\nStart everything with bundled services:\n\n```bash\n# Start all services (infrastructure + TestMesh + demo microservices)\ndocker-compose -f docker-compose.dev.yml up -d\n\n# Or start infrastructure only\ndocker-compose -f docker-compose.infra.yml up -d\ndocker-compose up -d\n\n# Or start with demo microservices\ndocker-compose -f docker-compose.infra.yml up -d\ndocker-compose up -d\ndocker-compose -f docker-compose.services.yml up -d\n```\n\n### Run Example E2E Test\n\n```bash\n# Run the complete end-to-end order flow\ncd cli\ngo run main.go run ../examples/microservices/e2e-order-flow.yaml\n```\n\nThis E2E test demonstrates:\n- HTTP requests to create users and products\n- Redis cache verification\n- Kafka event publishing and consumption\n- PostgreSQL data persistence\n- Inter-service communication\n- Notification generation\n\n**Result:**\n```\n✅ Flow completed successfully in 177ms\n   Total steps: 16\n   Passed: 16\n   Failed: 0\n```\n\n## Deployment Options\n\nTestMesh provides multiple Docker Compose files for different use cases:\n\n### `docker-compose.yml` (Production Ready)\n\n**Use when**: Deploying to production or using existing infrastructure\n\n```bash\ndocker-compose up -d\n```\n\n- ✅ Just TestMesh API and Dashboard\n- ✅ Expects external PostgreSQL and Redis\n- ✅ Configurable via environment variables\n- ✅ Port conflicts avoided (configurable ports)\n- ✅ Suitable for: Production, existing infrastructure, Docker deployments\n\n**Configuration**:\n```bash\n# .env file\nDATABASE_HOST=my-postgres-host\nDATABASE_PORT=5432\nREDIS_HOST=my-redis-host\nREDIS_PORT=6379\nAPI_PORT=5016\nDASHBOARD_PORT=3000\n```\n\n### `docker-compose.dev.yml` (Full Stack)\n\n**Use when**: Local development with everything bundled\n\n```bash\ndocker-compose -f docker-compose.dev.yml up -d\n```\n\n- ✅ Complete development stack\n- ✅ Bundled PostgreSQL, Redis, Kafka\n- ✅ TestMesh API and Dashboard\n- ✅ Demo microservices\n- ✅ All ports exposed on host\n- ✅ Suitable for: Local development, learning, demos\n\n**Ports used**: 5432, 6379, 9092-9093, 5016, 3000, 5001-5004\n\n### `docker-compose.infra.yml` (Infrastructure Only)\n\n**Use when**: You want bundled databases but deploy TestMesh separately\n\n```bash\ndocker-compose -f docker-compose.infra.yml up -d\n```\n\n- ✅ Just PostgreSQL, Redis, Kafka\n- ✅ No application services\n- ✅ Configurable ports to avoid conflicts\n- ✅ Suitable for: Local dev, CI/CD pipelines, testing\n\n**Configuration**:\n```bash\nPOSTGRES_PORT=5433  # Change if 5432 is in use\nREDIS_PORT=6380     # Change if 6379 is in use\nKAFKA_PORT=9093     # Change if 9092 is in use\n```\n\n### `docker-compose.services.yml` (Demo Microservices)\n\n**Use when**: Testing with demo e-commerce microservices\n\n```bash\ndocker-compose -f docker-compose.services.yml up -d\n```\n\n- ✅ Demo microservices only\n- ✅ Connects to external infrastructure\n- ✅ Suitable for: E2E testing, demonstrations\n\n**Ports**: 5001-5004 (configurable)\n\n### Combined Usage Examples\n\n**Scenario 1**: Local dev with custom Postgres port\n```bash\n# Start infrastructure on custom ports\nPOSTGRES_PORT=5433 REDIS_PORT=6380 docker-compose -f docker-compose.infra.yml up -d\n\n# Start TestMesh pointing to custom ports\nDATABASE_PORT=5433 REDIS_PORT=6380 docker-compose up -d\n```\n\n**Scenario 2**: Use existing services\n```bash\n# Create .env with your connection details\ncat > .env << EOF\nDATABASE_HOST=my-rds-instance.amazonaws.com\nDATABASE_PORT=5432\nREDIS_HOST=my-elasticache.amazonaws.com\nREDIS_PORT=6379\nEOF\n\n# Start TestMesh\ndocker-compose up -d\n```\n\n**Scenario 3**: Full local setup with different API port\n```bash\nAPI_PORT=8080 DASHBOARD_PORT=8081 docker-compose -f docker-compose.dev.yml up -d\n# API: http://localhost:8080\n# Dashboard: http://localhost:8081\n```\n\n**Scenario 4**: Production with external RDS + ElastiCache\n```bash\n# Pull pre-built images\ndocker pull testmesh/api:latest\ndocker pull testmesh/dashboard:latest\n\n# Start with production config\ndocker-compose up -d\n```\n\n**📖 For detailed Docker setup guide**: See [DOCKER_SETUP.md](DOCKER_SETUP.md) for:\n- Complete port configuration reference\n- Troubleshooting common issues\n- Network architecture details\n- CI/CD integration examples\n\n### 3. Create Your Own Test\n\n```yaml\n# my-test.yaml\nflow:\n  name: \"API Health Check\"\n  steps:\n    - id: check_health\n      action: http_request\n      config:\n        method: GET\n        url: \"http://localhost:5001/health\"\n      assert:\n        - status == 200\n        - body.status == \"healthy\"\n```\n\n```bash\ncd cli\ngo run main.go run my-test.yaml\n```\n\n## Test Definition\n\n### Basic HTTP Test\n```yaml\nflow:\n  name: \"User Creation Flow\"\n  steps:\n    - id: create_user\n      action: http_request\n      config:\n        method: POST\n        url: \"http://localhost:5001/api/v1/users\"\n        headers:\n          Content-Type: application/json\n        body:\n          name: \"John Doe\"\n          email: \"john@example.com\"\n      assert:\n        - status == 201\n        - body.id != null\n      output:\n        user_id: $.body.id\n```\n\n### Database Verification\n```yaml\n    - id: verify_in_db\n      action: database_query\n      config:\n        connection_string: \"postgresql://testmesh:testmesh_dev@localhost:5432/testmesh\"\n        query: \"SELECT * FROM user_service.users WHERE id = $1\"\n        params: [\"{{user_id}}\"]\n      assert:\n        - row_count == 1\n        - rows[0].email == \"john@example.com\"\n```\n\n### Kafka Event Testing\n```yaml\n    - id: verify_kafka_event\n      action: kafka_consumer\n      config:\n        brokers: \"localhost:9093\"\n        topic: \"user.created\"\n        group_id: \"testmesh-test\"\n        timeout: 10s\n      assert:\n        - messages.length > 0\n        - messages[0].value.user_id == user_id\n```\n\n### Redis Cache Check\n```yaml\n    - id: verify_cache\n      action: redis_get\n      config:\n        host: localhost\n        port: 6379\n        key: \"user:{{user_id}}\"\n      assert:\n        - value != null\n```\n\n## CLI Commands\n\n```bash\n# Run a flow\ngo run main.go run <flow.yaml>\n\n# Validate flow syntax\ngo run main.go validate <flow.yaml>\n\n# Available commands\ngo run main.go --help\n```\n\n## Architecture\n\nTestMesh is built as a **modular monolith** - a single Go service with clear domain boundaries:\n\n```\n┌─────────────┬───────────────┬───────────────┐\n│  CLI Tool   │   Dashboard   │   API Client  │\n└──────┬──────┴───────┬───────┴───────┬───────┘\n       │              │               │\n       └──────────────┴───────────────┘\n                      │\n       ┌──────────────┴──────────────────┐\n       │   TestMesh API Server (Go)      │\n       ├─────────────────────────────────┤\n       │  ┌────────────────────────────┐ │\n       │  │ API Domain                 │ │  REST API + WebSocket\n       │  └──────────┬─────────────────┘ │\n       │  ┌──────────▼─────────────────┐ │\n       │  │ Runner Domain              │ │  Flow execution engine\n       │  └──────────┬─────────────────┘ │\n       │  ┌──────────▼─────────────────┐ │\n       │  │ Storage Domain             │ │  Data persistence\n       │  └────────────────────────────┘ │\n       └──────────────┬──────────────────┘\n                      │\n       ┌──────────────┴──────────────────┐\n       │  PostgreSQL + Redis + Kafka     │\n       └─────────────────────────────────┘\n```\n\n**Domains:**\n- **API** - HTTP handlers, WebSocket, middleware\n- **Runner** - Test execution engine with action handlers\n- **Scheduler** - Cron-based test scheduling\n- **Storage** - Data models and repositories\n- **MCP** - Model Context Protocol for AI integration\n- **Shared** - Configuration, database, logging\n\nSee [docs/architecture/ARCHITECTURE.md](./docs/architecture/ARCHITECTURE.md) for complete architecture details.\n\n## Tech Stack\n\n### Backend\n- **Go 1.23+** - Primary language\n- **Gin** - HTTP framework\n- **GORM** - PostgreSQL ORM\n- **Viper** - Configuration management\n- **Zap** - Structured logging\n\n### Frontend\n- **Next.js 16** - React framework\n- **TypeScript** - Type safety\n- **Tailwind CSS** - Styling\n- **shadcn/ui** - UI components\n\n### Infrastructure\n- **PostgreSQL** - Primary database\n- **Redis** - Caching and sessions\n- **Kafka** - Event streaming\n- **Docker** - Containerization\n\n## Documentation\n\n### Getting Started\n- **[CLAUDE.md](./CLAUDE.md)** - Quick reference for developers\n- **[QUICKSTART.md](./docs/planning/QUICKSTART.md)** - Detailed getting started guide\n\n### Architecture\n- **[ARCHITECTURE.md](./docs/architecture/ARCHITECTURE.md)** - Complete system architecture\n- **[MODULAR_MONOLITH.md](./docs/architecture/MODULAR_MONOLITH.md)** - Architectural approach\n- **[TECH_STACK.md](./docs/architecture/TECH_STACK.md)** - Technology decisions\n- **[PROJECT_STRUCTURE.md](./docs/architecture/PROJECT_STRUCTURE.md)** - Code organization\n\n### Features\n- **[FLOW_DESIGN.md](./docs/features/FLOW_DESIGN.md)** - Flow execution design\n- **[YAML_SCHEMA.md](./docs/features/YAML_SCHEMA.md)** - Flow definition specification\n- **[MCP_INTEGRATION.md](./docs/features/MCP_INTEGRATION.md)** - AI integration via Model Context Protocol\n- **[CONTRACT_TESTING.md](./docs/features/CONTRACT_TESTING.md)** - Consumer-driven contracts\n- **[More...](./docs/README.md)** - Full documentation index\n\n### Microservices Demo\n- **[services/README.md](./demo-services/README.md)** - Demo microservices architecture guide\n- Complete e-commerce example with User, Product, Order, and Notification services\n- Shows HTTP, Kafka, Redis, and PostgreSQL integration patterns\n\n### Development\n- **[CODING_STANDARDS.md](./docs/process/CODING_STANDARDS.md)** - Code style guide\n- **[DEVELOPMENT_WORKFLOW.md](./docs/process/DEVELOPMENT_WORKFLOW.md)** - Git workflow\n- **[SECURITY_GUIDELINES.md](./docs/process/SECURITY_GUIDELINES.md)** - Security practices\n\n## Development\n\n### Run API Server\n```bash\ncd api\ngo run main.go\n# API runs on http://localhost:5016\n```\n\n### Run Dashboard\n```bash\ncd dashboard\nnpm install\nnpm run dev\n# Dashboard runs on http://localhost:3000\n```\n\n### Run CLI\n```bash\ncd cli\ngo run main.go run <flow.yaml>\n```\n\n### Start Everything with Docker\n```bash\n# All services\ndocker-compose up\n\n# Just infrastructure + microservices\ndocker-compose up postgres redis kafka user-service product-service order-service notification-service\n\n# Just API + Dashboard\ndocker-compose up api dashboard\n```\n\n## Examples\n\nCheck the [examples/](./examples/) directory for:\n- **microservices/** - Complete E2E flows testing all demo services\n  - `e2e-order-flow.yaml` - 16-step complete order journey\n  - `user-service-flow.yaml` - User CRUD with Redis sessions\n  - `product-service-flow.yaml` - Product operations with caching\n  - `kafka-messaging-flow.yaml` - Event streaming patterns\n- **emv-fare-testing/** - EMV fare calculation testing example\n\n## Health Checks\n\n```bash\n# API Server\ncurl http://localhost:5016/health\n\n# User Service\ncurl http://localhost:5001/health\n\n# Product Service\ncurl http://localhost:5002/health\n\n# Order Service\ncurl http://localhost:5003/health\n\n# Notification Service\ncurl http://localhost:5004/health\n```\n\n## Contributing\n\nContributions are welcome! Please read the development documentation in `docs/` before contributing.\n\n### Development Setup\n1. Install Go 1.23+\n2. Install Node.js 20+\n3. Install Docker & Docker Compose\n4. Clone the repository\n5. Run `docker-compose up` to start infrastructure\n\n## License\n\nMIT License - See [LICENSE](./LICENSE) for details.\n\n---\n\n**Get Started:** Check out [CLAUDE.md](./CLAUDE.md) for a quick development guide, or [docs/planning/QUICKSTART.md](./docs/planning/QUICKSTART.md) for detailed instructions.\n\n**Questions?** See the documentation in `docs/` or open an issue on GitHub.\n",
  "bytes": 14997,
  "sha": "459f9ab8cb748a712f833fbc86ec269ea7486f54219a1c4f4c9b89bf7a7f0a3a",
  "repo_slug": "test-mesh/testmesh",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_test_mesh_testmesh_testmesh_65081bfe/readme"
}