{"id":51118957,"url":"https://github.com/sulthonzh/api-contract-tester","last_synced_at":"2026-06-25T00:30:34.773Z","repository":{"id":363265508,"uuid":"1260824064","full_name":"sulthonzh/api-contract-tester","owner":"sulthonzh","description":"Comprehensive CLI tool for testing API contracts between frontend and backend systems","archived":false,"fork":false,"pushed_at":"2026-06-22T20:10:33.000Z","size":129,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T22:10:03.436Z","etag":null,"topics":["api","backend","cli","contract","frontend","testing","typescript","validation"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sulthonzh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T23:09:56.000Z","updated_at":"2026-06-21T19:33:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sulthonzh/api-contract-tester","commit_stats":null,"previous_names":["sulthonzh/api-contract-tester"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/sulthonzh/api-contract-tester","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fapi-contract-tester","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fapi-contract-tester/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fapi-contract-tester/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fapi-contract-tester/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sulthonzh","download_url":"https://codeload.github.com/sulthonzh/api-contract-tester/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fapi-contract-tester/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","cli","contract","frontend","testing","typescript","validation"],"created_at":"2026-06-25T00:30:34.685Z","updated_at":"2026-06-25T00:30:34.758Z","avatar_url":"https://github.com/sulthonzh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API Contract Tester\n\nComprehensive CLI tool for testing API contracts between frontend and backend systems. Validate endpoints, check responses, and generate detailed reports.\n\n## 🚀 Features\n\n- **Multi-format Support**: JSON and YAML schemas\n- **Endpoint Validation**: Test individual endpoints or entire APIs\n- **Response Schema Validation**: JSON schema validation for responses\n- **Multiple Output Formats**: Pretty console, JSON, YAML, and HTML reports\n- **Interactive Mode**: Guided setup and testing\n- **Parallel Testing**: Run tests in parallel for better performance\n- **Retry Logic**: Configurable retry attempts for flaky endpoints\n- **Header Validation**: Validate response headers\n- **Custom Configuration**: Override settings via CLI or config files\n- **Detailed Reports**: Comprehensive test reports with differences and metrics\n\n## 📦 Installation\n\n```bash\n# Install globally\nnpm install -g api-contract-tester\n\n# Or use npx\nnpx api-contract-tester --help\n```\n\n## 🛠️ Usage\n\n### Quick Start\n\n```bash\n# Run a quick test on your API\nact test\n\n# Test with a schema file\nact test -s ./api-schema.json\n\n# Test with custom options\nact test -u https://api.example.com -o json -v -p\n```\n\n### Configuration\n\nInitialize configuration:\n\n```bash\nact config --init\n```\n\nShow current configuration:\n\n```bash\nact config --show\n```\n\n### Schema Management\n\nGenerate schema template:\n\n```bash\nact schema --generate ./schema.json\n```\n\nValidate schema file:\n\n```bash\nact schema --validate ./schema.json\n```\n\n## 🔧 Configuration\n\n### Config File (`act.config.json`)\n\n```json\n{\n  \"baseUrl\": \"https://api.example.com\",\n  \"timeout\": 10000,\n  \"retries\": 3,\n  \"parallel\": false,\n  \"verbose\": false,\n  \"outputFormat\": \"pretty\",\n  \"headers\": {\n    \"Content-Type\": \"application/json\",\n    \"Authorization\": \"Bearer token123\"\n  }\n}\n```\n\n### API Schema Format\n\n```json\n{\n  \"baseUrl\": \"https://api.example.com\",\n  \"version\": \"1.0.0\",\n  \"endpoints\": [\n    {\n      \"path\": \"/api/users\",\n      \"method\": \"GET\",\n      \"headers\": {\n        \"Authorization\": \"Bearer token123\"\n      },\n      \"parameters\": {\n        \"query\": {\n          \"page\": 1,\n          \"limit\": 10\n        }\n      },\n      \"response\": {\n        \"status\": 200,\n        \"headers\": {\n          \"Content-Type\": \"application/json\"\n        },\n        \"schema\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"users\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"object\",\n                \"properties\": {\n                  \"id\": { \"type\": \"string\" },\n                  \"name\": { \"type\": \"string\" },\n                  \"email\": { \"type\": \"string\" }\n                },\n                \"required\": [\"id\", \"name\", \"email\"]\n              }\n            }\n          }\n        }\n      }\n    }\n  ],\n  \"security\": {\n    \"type\": \"Bearer\"\n  }\n}\n```\n\n### Test Suite Format\n\n```json\n{\n  \"name\": \"User API Tests\",\n  \"description\": \"Comprehensive user API testing suite\",\n  \"baseUrl\": \"https://api.example.com\",\n  \"preconditions\": {\n    \"headers\": {\n      \"Authorization\": \"Bearer token123\"\n    }\n  },\n  \"endpoints\": [\n    {\n      \"path\": \"/api/users\",\n      \"method\": \"GET\",\n      \"response\": {\n        \"status\": 200\n      }\n    }\n  ]\n}\n```\n\n## 📊 CLI Commands\n\n### Test Commands\n\n```bash\n# Basic test\nact test\n\n# With schema file\nact test -s ./schema.json\n\n# With test suite\nact test -t ./suite.json\n\n# Override base URL\nact test -u https://api.example.com\n\n# Output formats\nact test -o json          # JSON output\nact test -o yaml          # YAML output\nact test -o html          # HTML report\nact test -o pretty        # Pretty console (default)\n\n# Advanced options\nact test -v               # Verbose output\nact test -p               # Parallel execution\nact test --timeout 5000   # 5 second timeout\nact test --retries 5      # 5 retry attempts\n```\n\n### Configuration Management\n\n```bash\nact config --init         # Initialize config\nact config --show         # Show current config\nact config --edit         # Edit config file\n```\n\n### Schema Management\n\n```bash\nact schema --generate ./schema.json  # Generate schema template\nact schema --validate ./schema.json  # Validate schema file\n```\n\n## 📈 Output Examples\n\n### Pretty Console Output\n\n```\n📋 API Contract Test Report\n=========================\nSuite: API Schema Tests\nTimestamp: 2023-01-01T10:00:00.000Z\nDuration: 2500ms\nTotal Tests: 5\nPassed: 3\nFailed: 1\nWarnings: 1\nSuccess Rate: 60%\nAverage Response Time: 450ms\n\n✅ GET /api/users\n   Endpoint response matches expected schema\n   Duration: 200ms\n   Time: 2023-01-01T10:00:00.100Z\n\n❌ POST /api/users\n   Status code mismatch: expected 201, got 400\n   Duration: 1500ms\n   Time: 2023-01-01T10:00:01.200Z\n   Differences:\n     • Status code: expected 201, got 400\n\n⚠️ GET /api/posts\n   Endpoint response matches expected schema (Header mismatches: 1 found)\n   Duration: 150ms\n   Time: 2023-01-01T10:00:01.350Z\n```\n\n### JSON Report\n\n```json\n{\n  \"suite\": \"API Schema Tests\",\n  \"timestamp\": \"2023-01-01T10:00:00.000Z\",\n  \"duration\": 2500,\n  \"totalTests\": 5,\n  \"passed\": 3,\n  \"failed\": 1,\n  \"warnings\": 1,\n  \"results\": [\n    {\n      \"endpoint\": \"GET /api/users\",\n      \"method\": \"GET\",\n      \"status\": \"pass\",\n      \"message\": \"Endpoint response matches expected schema\",\n      \"details\": {\n        \"request\": { \"method\": \"GET\", \"url\": \"/api/users\" },\n        \"response\": { \"status\": 200, \"data\": { \"users\": [] } }\n      },\n      \"timestamp\": \"2023-01-01T10:00:00.100Z\",\n      \"duration\": 200\n    }\n  ],\n  \"summary\": {\n    \"successRate\": 60,\n    \"averageResponseTime\": 450,\n    \"errorRate\": 20\n  }\n}\n```\n\n## 🔍 Advanced Features\n\n### Parallel Testing\n\nRun multiple endpoint tests in parallel for better performance:\n\n```bash\nact test -p -s ./large-schema.json\n```\n\n### Custom Headers\n\nAdd custom headers to all requests:\n\n```json\n{\n  \"headers\": {\n    \"Authorization\": \"Bearer your-token\",\n    \"X-Custom-Header\": \"value\"\n  }\n}\n```\n\n### Query Parameters\n\nTest endpoints with query parameters:\n\n```json\n{\n  \"path\": \"/api/search\",\n  \"method\": \"GET\",\n  \"parameters\": {\n    \"query\": {\n      \"q\": \"test\",\n      \"limit\": 10,\n      \"offset\": 0\n    }\n  }\n}\n```\n\n### Request Bodies\n\nTest POST/PUT/PATCH with request bodies:\n\n```json\n{\n  \"path\": \"/api/users\",\n  \"method\": \"POST\",\n  \"parameters\": {\n    \"body\": {\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\",\n      \"active\": true\n    }\n  },\n  \"response\": {\n    \"status\": 201,\n    \"schema\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": { \"type\": \"string\" },\n        \"name\": { \"type\": \"string\" },\n        \"email\": { \"type\": \"string\" }\n      },\n      \"required\": [\"id\", \"name\", \"email\"]\n    }\n  }\n}\n```\n\n## 🧪 Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd api-contract-tester\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Project Structure\n\n```\napi-contract-tester/\n├── src/\n│   ├── index.ts          # Main entry point\n│   ├── cli.ts            # CLI interface\n│   ├── contract-validator.ts  # Core validation logic\n│   ├── config-manager.ts     # Configuration management\n│   ├── report-generator.ts   # Report generation\n│   └── types.ts         # TypeScript type definitions\n├── tests/\n│   ├── contract-validator.test.ts\n│   ├── config-manager.test.ts\n│   ├── cli.test.ts\n│   └── report-generator.test.ts\n├── examples/            # Example schemas and configurations\n└── dist/                # Compiled output\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🔗 Related Tools\n\n- [API Documentation Generator](https://github.com/sulthonzh/api-docs-generator)\n- [API Performance Monitor](https://github.com/sulthonzh/api-performance-monitor)\n- [API Security Scanner](https://github.com/sulthonzh/api-security-scanner)\n\n## 🙏 Acknowledgments\n\n- Built with [Commander.js](https://github.com/tj/commander.js) for CLI interface\n- Uses [Ajv](https://github.com/ajv-validator/ajv) for JSON schema validation\n- Styled with [Chalk](https://github.com/chalk/chalk) for terminal colors\n- Uses [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) for interactive prompts","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fapi-contract-tester","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsulthonzh%2Fapi-contract-tester","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fapi-contract-tester/lists"}