commit 12a5ba6a10c5601e314805d0ff0cadbeaeba144d Author: Zhongwei Li Date: Sun Nov 30 08:22:57 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..c8e8594 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "api-test-automation", + "description": "Automated API endpoint testing with request generation, validation, and comprehensive test coverage", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugins", + "email": "[email protected]" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bcc8997 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# api-test-automation + +Automated API endpoint testing with request generation, validation, and comprehensive test coverage diff --git a/agents/api-tester.md b/agents/api-tester.md new file mode 100644 index 0000000..500fa9f --- /dev/null +++ b/agents/api-tester.md @@ -0,0 +1,192 @@ +--- +description: Specialized agent for automated API endpoint testing and validation +capabilities: ["rest-api-testing", "graphql-testing", "authentication", "validation", "contract-testing"] +--- + +# API Test Automation Agent + +You are a specialized API testing agent that automates endpoint testing with comprehensive validation and reporting. + +## Your Capabilities + +### 1. REST API Testing +- **CRUD operations** - GET, POST, PUT, PATCH, DELETE +- **Request validation** - Headers, body, query parameters +- **Response validation** - Status codes, headers, body structure +- **Authentication** - Bearer tokens, API keys, OAuth, Basic Auth +- **Error scenarios** - 4xx/5xx responses, invalid inputs + +### 2. GraphQL Testing +- **Query testing** - Read operations with various selectors +- **Mutation testing** - Create, update, delete operations +- **Subscription testing** - Real-time data streams +- **Error handling** - GraphQL error responses +- **Schema validation** - Type checking, required fields + +### 3. API Contract Testing +- **OpenAPI/Swagger** - Validate against spec +- **Schema validation** - JSON Schema, Joi, Yup +- **Breaking change detection** - Compare API versions +- **Documentation sync** - Ensure docs match implementation + +### 4. Test Scenario Generation +- **Happy path tests** - Successful operations +- **Edge cases** - Boundary values, empty data +- **Error cases** - Invalid inputs, unauthorized access +- **Performance tests** - Response time validation +- **Security tests** - Injection attempts, auth bypass + +## When to Activate + +Activate when the user needs to: +- Test REST or GraphQL API endpoints +- Validate API responses against schemas +- Generate API test suites +- Automate endpoint regression testing +- Verify authentication and authorization +- Check API performance and reliability + +## Approach + +### For Test Generation + +1. **Analyze API specification** (if available) + - OpenAPI/Swagger docs + - GraphQL schema + - Postman collections + - Existing API code + +2. **Identify endpoints to test** + - List all HTTP methods per route + - Note authentication requirements + - Identify related endpoints + +3. **Generate test cases** + - Valid requests (happy path) + - Invalid requests (error handling) + - Edge cases (boundaries, nulls) + - Authentication scenarios + - Authorization checks (different roles) + +4. **Create test file** + - Framework-specific syntax (Jest, pytest, RSpec) + - Request builders + - Response assertions + - Mock data factories + - Setup/teardown hooks + +### For Test Execution + +1. **Setup phase** + - Load environment variables + - Initialize HTTP client + - Authenticate (if needed) + - Prepare test data + +2. **Execute tests** + - Send HTTP requests + - Capture responses + - Validate status codes + - Check response structure + - Verify response data + +3. **Report results** + - Passed/failed tests + - Response times + - Error details + - Coverage metrics + +4. **Cleanup** + - Delete test data + - Clear authentication + - Reset state + +## Test Structure + +Generate tests following this pattern: + +```javascript +describe('API Endpoint: POST /api/users', () => { + describe('Authentication', () => { + it('should return 401 without auth token', async () => { + const response = await api.post('/api/users', userData); + expect(response.status).toBe(401); + }); + }); + + describe('Success scenarios', () => { + it('should create user with valid data', async () => { + const response = await api.post('/api/users', validUser, { auth: token }); + expect(response.status).toBe(201); + expect(response.data).toHaveProperty('id'); + expect(response.data.email).toBe(validUser.email); + }); + }); + + describe('Validation errors', () => { + it('should return 400 for invalid email', async () => { + const response = await api.post('/api/users', { email: 'invalid' }, { auth: token }); + expect(response.status).toBe(400); + expect(response.data.errors).toContain('email'); + }); + }); + + describe('Edge cases', () => { + it('should handle duplicate email gracefully', async () => { + await api.post('/api/users', existingUser, { auth: token }); + const response = await api.post('/api/users', existingUser, { auth: token }); + expect(response.status).toBe(409); + }); + }); +}); +``` + +## Validation Rules + +Always validate: +- **Status codes** - Correct HTTP status +- **Response structure** - Expected JSON shape +- **Data types** - String, number, boolean, array, object +- **Required fields** - All mandatory fields present +- **Data formats** - Email, URL, date, UUID formats +- **Response headers** - Content-Type, Cache-Control, etc. +- **Response time** - Performance thresholds +- **Error messages** - Clear, helpful error responses + +## Authentication Patterns + +Handle common auth patterns: +- **Bearer tokens** - `Authorization: Bearer ` +- **API keys** - Header or query parameter +- **OAuth 2.0** - Token exchange flow +- **Basic Auth** - Username:password encoding +- **Session cookies** - Cookie-based authentication +- **JWT tokens** - Validate and refresh tokens + +## Tools and Libraries + +Use appropriate tools for the language: +- **JavaScript/TypeScript**: axios, supertest, node-fetch +- **Python**: requests, httpx, pytest-httpx +- **Java**: RestAssured, OkHttp +- **Go**: net/http, httptest +- **Ruby**: Faraday, HTTParty + +## Output Format + +Provide: +1. **Complete test file** with all necessary imports +2. **Test data fixtures** or factories +3. **Authentication helpers** (if needed) +4. **README** with setup instructions +5. **Environment variables** needed + +## Best Practices + +- **Test isolation** - Each test is independent +- **Clear descriptions** - Descriptive test names +- **Proper assertions** - Validate all critical fields +- **Error handling** - Test both success and failure +- **Performance checks** - Include response time assertions +- **Documentation** - Comment complex test scenarios +- **Maintainability** - DRY principle, reusable helpers diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..9e764b6 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/testing/api-test-automation", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d4b8ed8b59c7cde365b3117c8f3f79419bb0e17b", + "treeHash": "0f98c7342b912071f66db55ca0dc8835f1324ed2d02bda76e0bcf4a9c7b18e78", + "generatedAt": "2025-11-28T10:18:09.056625Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "api-test-automation", + "description": "Automated API endpoint testing with request generation, validation, and comprehensive test coverage", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "0bef6826f0791fa91da4ef3857b01731de0acfa6b6b45f2fb79a4132de9b6723" + }, + { + "path": "agents/api-tester.md", + "sha256": "a8991c8ff5f69446e2009caf9cc6d4c16c238e59699f71dc6dadcb1bbb3014a4" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "ed1b36565688e8a2ff97022fb4a71b376dbc9cf60b7eaef0cef20f81e0387c58" + }, + { + "path": "skills/api-test-automation/SKILL.md", + "sha256": "75c776903c44b9d7f6706d9894fdba0dfddc8c8c08d62cd49cae556549d75093" + }, + { + "path": "skills/api-test-automation/references/README.md", + "sha256": "ecce398fa924ab939701b78fc0e22e219d00ce3fb5972e97b509665017c1a0d8" + }, + { + "path": "skills/api-test-automation/scripts/README.md", + "sha256": "ca410993d6c53bb2e3bc82d488bddf4a560c6945eebe05014b14ac11035ac543" + }, + { + "path": "skills/api-test-automation/assets/example_openapi.yaml", + "sha256": "c500b0a9301805853606786c70a4a4c6e8f616abe6d53ba4016184f5acb9c24d" + }, + { + "path": "skills/api-test-automation/assets/test_suite_template.js", + "sha256": "ba2d7e25daf5aa7dc45cc5e16446f1d49d45745243672a9e365c7d05f5ed5ddc" + }, + { + "path": "skills/api-test-automation/assets/example_graphql_schema.graphql", + "sha256": "f357c821180c5a441ebf331ea9c6af3956d96d666eb5b60e2a9c2ac888b3da0b" + }, + { + "path": "skills/api-test-automation/assets/README.md", + "sha256": "32db349e9ff00390641a736988dbb724e3471c3c6c326bca1da067e04b0c322c" + } + ], + "dirSha256": "0f98c7342b912071f66db55ca0dc8835f1324ed2d02bda76e0bcf4a9c7b18e78" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/api-test-automation/SKILL.md b/skills/api-test-automation/SKILL.md new file mode 100644 index 0000000..1a76eec --- /dev/null +++ b/skills/api-test-automation/SKILL.md @@ -0,0 +1,53 @@ +--- +name: automating-api-testing +description: | + This skill automates API endpoint testing, including request generation, validation, and comprehensive test coverage for REST and GraphQL APIs. It is used when the user requests API testing, contract testing, or validation against OpenAPI specifications. The skill analyzes API endpoints and generates test suites covering CRUD operations, authentication flows, and security aspects. It also validates response status codes, headers, and body structure. Use this skill when the user mentions "API testing", "REST API tests", "GraphQL API tests", "contract tests", or "OpenAPI validation". +allowed-tools: Read, Write, Edit, Grep, Glob, Bash +version: 1.0.0 +--- + +## Overview + +This skill empowers Claude to automatically generate and execute comprehensive API tests for REST and GraphQL endpoints. It ensures thorough validation, covers various authentication methods, and performs contract testing against OpenAPI specifications. + +## How It Works + +1. **Analyze API Definition**: The skill parses the provided API definition (e.g., OpenAPI/Swagger file, code files) or infers it from usage. +2. **Generate Test Cases**: Based on the API definition, it creates test cases covering different scenarios, including CRUD operations, authentication, and error handling. +3. **Execute Tests and Validate Responses**: The skill executes the generated tests and validates the responses against expected status codes, headers, and body structures. + +## When to Use This Skill + +This skill activates when you need to: +- Generate comprehensive API tests for REST endpoints. +- Create GraphQL API tests covering queries, mutations, and subscriptions. +- Validate API contracts against OpenAPI/Swagger specifications. +- Test API authentication flows, including login, refresh, and protected endpoints. + +## Examples + +### Example 1: Generating REST API Tests + +User request: "Generate API tests for the user management endpoints in src/routes/users.js" + +The skill will: +1. Analyze the user management endpoints in the specified file. +2. Generate a test suite covering CRUD operations (create, read, update, delete) for user resources. + +### Example 2: Creating GraphQL API Tests + +User request: "Create GraphQL API tests for the product queries and mutations" + +The skill will: +1. Analyze the product queries and mutations in the GraphQL schema. +2. Generate tests to verify the functionality and data integrity of these operations. + +## Best Practices + +- **API Definition**: Provide a clear and accurate API definition (e.g., OpenAPI/Swagger file) for optimal test generation. +- **Authentication Details**: Specify the authentication method and credentials required to access the API endpoints. +- **Contextual Information**: Provide context about the API's purpose and usage to guide the test generation process. + +## Integration + +This skill can integrate with other plugins to retrieve API definitions from various sources, such as code repositories or API gateways. It can also be combined with reporting tools to generate detailed test reports and dashboards. \ No newline at end of file diff --git a/skills/api-test-automation/assets/README.md b/skills/api-test-automation/assets/README.md new file mode 100644 index 0000000..f73324d --- /dev/null +++ b/skills/api-test-automation/assets/README.md @@ -0,0 +1,7 @@ +# Assets + +Bundled resources for api-test-automation skill + +- [ ] test_suite_template.js: Template for generating API test suites, including placeholders for different test cases and assertions. +- [ ] example_openapi.yaml: Example OpenAPI specification file for demonstration and testing purposes. +- [ ] example_graphql_schema.graphql: Example GraphQL schema file for testing GraphQL APIs. diff --git a/skills/api-test-automation/assets/example_graphql_schema.graphql b/skills/api-test-automation/assets/example_graphql_schema.graphql new file mode 100644 index 0000000..bcda502 --- /dev/null +++ b/skills/api-test-automation/assets/example_graphql_schema.graphql @@ -0,0 +1,98 @@ +# Example GraphQL schema file for testing GraphQL APIs. +# This schema defines a simple book catalog with authors. + +# Types +type Book { + id: ID! + title: String! + author: Author! + publicationYear: Int + genre: String +} + +type Author { + id: ID! + name: String! + books: [Book!]! +} + +# Queries +type Query { + # Get a book by its ID + book(id: ID!): Book + + # Get all books + books: [Book!]! + + # Get an author by their ID + author(id: ID!): Author + + # Get all authors + authors: [Author!]! + + # Search for books by title or author name + search(query: String!): [Book!]! +} + +# Mutations +type Mutation { + # Create a new book + createBook( + title: String! + authorId: ID! + publicationYear: Int + genre: String + ): Book + + # Update an existing book + updateBook( + id: ID! + title: String + authorId: ID + publicationYear: Int + genre: String + ): Book + + # Delete a book by its ID + deleteBook(id: ID!): ID + + # Create a new author + createAuthor(name: String!): Author +} + +# Input types (optional, for more complex mutations) +# input CreateBookInput { +# title: String! +# authorId: ID! +# publicationYear: Int +# genre: String +# } + +# Placeholder for subscriptions (if needed) +# type Subscription { +# newBook: Book +# } + +# Further instructions: +# 1. This is a basic example. Extend it with more complex types, fields, and relationships as needed. +# 2. Consider adding input types for mutations to improve clarity and validation. +# 3. Implement resolvers for each query and mutation to connect to your data source. +# 4. Use directives for authorization, caching, and other features. +# 5. Use scalars for custom data types (e.g., Date, URL). +# 6. Example query to get a specific book: +# query { +# book(id: "123") { +# id +# title +# author { +# name +# } +# } +# } +# 7. Example mutation to create a book: +# mutation { +# createBook(title: "New Book", authorId: "456", publicationYear: 2023, genre: "Fiction") { +# id +# title +# } +# } \ No newline at end of file diff --git a/skills/api-test-automation/assets/example_openapi.yaml b/skills/api-test-automation/assets/example_openapi.yaml new file mode 100644 index 0000000..5db9e9a --- /dev/null +++ b/skills/api-test-automation/assets/example_openapi.yaml @@ -0,0 +1,216 @@ +# OpenAPI Specification for Example API + +openapi: 3.0.0 +info: + title: Example API + version: 1.0.0 + description: A sample API for demonstration purposes. + termsOfService: REPLACE_ME # Add your terms of service URL here + contact: + name: API Support + url: REPLACE_ME # Add your support URL here + email: support@example.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + +servers: + - url: https://api.example.com/v1 + description: Production server + +paths: + /users: + get: + summary: Get all users + description: Retrieves a list of all users. + operationId: getUsers + tags: + - users + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' + '500': + description: Internal server error + post: + summary: Create a new user + description: Creates a new user in the system. + operationId: createUser + tags: + - users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserCreate' + responses: + '201': + description: User created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '400': + description: Bad request + '500': + description: Internal server error + + /users/{userId}: + get: + summary: Get user by ID + description: Retrieves a user by their ID. + operationId: getUserById + tags: + - users + parameters: + - name: userId + in: path + description: ID of the user to retrieve. + required: true + schema: + type: integer + format: int64 + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '404': + description: User not found + '500': + description: Internal server error + put: + summary: Update user by ID + description: Updates an existing user. + operationId: updateUser + tags: + - users + parameters: + - name: userId + in: path + description: ID of the user to update. + required: true + schema: + type: integer + format: int64 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserUpdate' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '400': + description: Bad request + '404': + description: User not found + '500': + description: Internal server error + delete: + summary: Delete user by ID + description: Deletes a user by their ID. + operationId: deleteUser + tags: + - users + parameters: + - name: userId + in: path + description: ID of the user to delete. + required: true + schema: + type: integer + format: int64 + responses: + '204': + description: User deleted successfully (No Content) + '404': + description: User not found + '500': + description: Internal server error + +components: + schemas: + User: + type: object + properties: + id: + type: integer + format: int64 + description: Unique identifier for the user + username: + type: string + description: User's username + email: + type: string + format: email + description: User's email address + firstName: + type: string + description: User's first name + lastName: + type: string + description: User's last name + required: + - id + - username + - email + + UserCreate: + type: object + properties: + username: + type: string + description: User's username + email: + type: string + format: email + description: User's email address + firstName: + type: string + description: User's first name + lastName: + type: string + description: User's last name + required: + - username + - email + + UserUpdate: + type: object + properties: + username: + type: string + description: User's username + email: + type: string + format: email + description: User's email address + firstName: + type: string + description: User's first name + lastName: + type: string + description: User's last name + + securitySchemes: + bearerAuth: # Define security scheme name + type: http + scheme: bearer + bearerFormat: JWT + +security: + - bearerAuth: [] # Apply the security scheme to all endpoints (globally) \ No newline at end of file diff --git a/skills/api-test-automation/assets/test_suite_template.js b/skills/api-test-automation/assets/test_suite_template.js new file mode 100644 index 0000000..b7cc9bc --- /dev/null +++ b/skills/api-test-automation/assets/test_suite_template.js @@ -0,0 +1,99 @@ +/** + * test_suite_template.js + * + * Template for generating API test suites. This template provides a structure + * for creating comprehensive test cases for various API endpoints. + * + * @example + * // Example usage (after replacing placeholders): + * const testSuite = require('./test_suite_template'); + * + * const config = { + * baseURL: 'https://api.example.com', + * endpoint: '/users', + * method: 'GET', + * description: 'Retrieve all users' + * }; + * + * const testCase = testSuite(config); + * + * describe(config.description, () => { + * it('should return a 200 OK status', async () => { + * const response = await testCase.request(); + * expect(response.status).toBe(200); + * }); + * // Add more test cases here... + * }); + */ + +/** + * Generates a test suite based on the provided configuration. + * + * @param {object} config - Configuration object for the test suite. + * @param {string} config.baseURL - The base URL of the API. + * @param {string} config.endpoint - The API endpoint to test. + * @param {string} config.method - The HTTP method to use (GET, POST, PUT, DELETE, etc.). + * @param {string} config.description - A description of the test case. + * @param {object} [config.headers] - Optional headers to include in the request. + * @param {object} [config.body] - Optional request body. + * @param {string} [config.authenticationType] - Optional authentication type (e.g., 'Bearer', 'OAuth', 'API Key'). + * @param {string} [config.authenticationToken] - Optional authentication token or API key. + * @returns {object} An object containing the request function. + */ +module.exports = (config) => { + const axios = require('axios'); // Consider making axios a configurable dependency if needed + + /** + * Executes the API request based on the configuration. + * + * @async + * @function request + * @returns {Promise} A promise that resolves to the API response. + * @throws {Error} If the request fails. + */ + async function request() { + try { + const requestConfig = { + method: config.method, + url: config.baseURL + config.endpoint, + headers: config.headers || {}, + data: config.body || null, // Use data for POST/PUT requests, params for GET + // params: config.method === 'GET' ? config.body : null // Alternate: use params for GET requests + }; + + // Authentication handling + if (config.authenticationType === 'Bearer' && config.authenticationToken) { + requestConfig.headers.Authorization = `Bearer ${config.authenticationToken}`; + } else if (config.authenticationType === 'API Key' && config.authenticationToken) { + // Example API Key header - adjust based on API requirements + requestConfig.headers['X-API-Key'] = config.authenticationToken; + } // Add more authentication types as needed + + const response = await axios(requestConfig); + return response; + } catch (error) { + // Handle errors appropriately (e.g., log, re-throw, or return a custom error object) + console.error(`Request failed for ${config.description}:`, error.message); + throw error; // Re-throw the error for the test to handle + } + } + + return { + request, + + // Add more helper functions here if needed (e.g., for data validation) + validateResponseSchema: (response, schema) => { + // Placeholder: Implement schema validation logic using a library like Joi or Ajv + // Example: + // const validationResult = schema.validate(response.data); + // if (validationResult.error) { + // throw new Error(`Schema validation failed: ${validationResult.error.message}`); + // } + }, + extractDataFromResponse: (response, path) => { + // Placeholder: Implement logic to extract data from the response using a library like lodash.get + // Example: + // return _.get(response.data, path); + } + }; +}; \ No newline at end of file diff --git a/skills/api-test-automation/references/README.md b/skills/api-test-automation/references/README.md new file mode 100644 index 0000000..61cfd22 --- /dev/null +++ b/skills/api-test-automation/references/README.md @@ -0,0 +1,7 @@ +# References + +Bundled resources for api-test-automation skill + +- [ ] api_testing_best_practices.md: Detailed guide on API testing best practices, covering different testing types and strategies. +- [ ] openapi_specification.md: Documentation on how to use OpenAPI specifications for contract testing and API validation. +- [ ] graphql_testing_guide.md: Comprehensive guide on testing GraphQL APIs, including queries, mutations, and subscriptions. diff --git a/skills/api-test-automation/scripts/README.md b/skills/api-test-automation/scripts/README.md new file mode 100644 index 0000000..5e4ff1d --- /dev/null +++ b/skills/api-test-automation/scripts/README.md @@ -0,0 +1,7 @@ +# Scripts + +Bundled resources for api-test-automation skill + +- [ ] generate_test_suite.py: Generates comprehensive test suites for REST and GraphQL APIs based on endpoint analysis and specifications. +- [ ] validate_api_response.py: Validates API responses against predefined schemas or OpenAPI specifications. +- [ ] authentication_test.py: Automates authentication testing, including various methods like Bearer tokens, OAuth, and API keys.