httpyac API Testing

Work with httpyac .http files to test and validate HTTP, gRPC, GraphQL, and WebSocket APIs following established patterns and best practices.

Quick Start

This Skill provides comprehensive rules for working with httpyac. Before any httpyac task:

1. Read HTTPYAC-RULES.md for all protocol-specific rules
2. STRICTLY follow these rules while creating or executing .http files
3. RESPECT rules by severity: Critical [C] > High [H] > Medium [M] > Low [L]
4. Understand proto file paths relative to .http file location for gRPC

When to Use This Skill

• Creating new .http files for API testing
• Writing HTTP REST requests with authentication
• Creating gRPC requests (unary or streaming)
• Crafting GraphQL queries and mutations
• Building WebSocket test scenarios
• Validating API contracts against proto definitions
• Debugging API integration issues
• Executing API tests via CLI

Rule Categories Overview

The HTTPYAC-RULES.md file contains detailed rules in these categories:

• [P] Protocol Selection: Choose appropriate protocol based on service definition
• [H] HTTP Requests: REST API patterns, headers, authentication, body formats
• [G] gRPC Requests: Proto imports, unary and streaming patterns, message formatting
• [Q] GraphQL Requests: Queries, mutations, fragments, variable passing
• [W] WebSocket Requests: Connections, streaming, bidirectional communication
• [M] Meta Data and Variables: Request naming, dependencies, variable scoping
• [S] Scripting and Testing: Pre/post-request scripts, assertions, async patterns
• [E] Environment and Configuration: CLI execution, proto path resolution, variables

Rule Severity Levels

• [C]ritical: Must never be violated - will cause execution failure
• [H]igh: Should almost never be violated - core patterns
• [M]edium: Follow unless good reason not to - best practices
• [L]ow: Guidelines and preferences - style choices

MCP Integration

This skill works best with:

serena MCP - for proto file discovery and navigation:

• find_file: Locate proto files and existing .http examples
• read_file: Read proto definitions to understand service contracts
• search_for_pattern: Find existing patterns across .http files
• get_symbols_overview: Understand proto service structure
• find_symbol: Locate specific service methods

context7 MCP - for up-to-date httpyac documentation:

• resolve-library-id: Get httpyac library ID
• get-library-docs: Fetch documentation for specific httpyac features

Troubleshooting

Proto file not found:

• Verify proto path is relative from .http file to proto file
• Count directories from .http file location to proto location
• Ensure includeDirs points to proto root directory for nested imports
• Use serena MCP find_file to locate proto files

gRPC connection failure:

• Verify {{HOST}} variable is defined
• Check service and method names match proto exactly
• Ensure Authorization header if required
• Check gRPC status code in response (0 = success)

Variable not defined:

• Check if request has @name metadata for capture
• Verify @ref or @forceRef for dependent requests
• Check variable syntax: {{variable}} not {variable}
• Ensure referenced request executed before current request

CLI execution error:

• Use -o=body for output format and -a to execute all requests
• Example: httpyac -o=body -a ./path/to/file.http
• Check if .http file path is correct relative to current directory

Example Workflow

When creating a new API test:

1. Locate the proto file: find_file with pattern
2. Read proto to understand service contract: read_file
3. Create .http file in desired location
4. Calculate proto path relative to .http file location
5. Add proto import with correct relative path and includeDirs
6. Write request with proper protocol syntax
7. Add variables and authentication
8. Execute from CLI: httpyac -o=body -a ./path/to/file.http
9. Add assertions in post-request script if needed