gRPC Error Code Mapping Test Prompt Template

This prompt is designed for backend test engineers and service reliability developers who need to validate that a gRPC service correctly maps internal domain errors to the appropriate canonical gRPC status codes. The job-to-be-done is generating a targeted test suite that triggers specific failure conditions and asserts the resulting grpc-status, grpc-message, and custom metadata entries in the response trailers. Use this when you have a protobuf service definition and a documented error-handling specification, and you need to move from manual ad-hoc testing to a structured, repeatable validation harness.

The ideal user has access to the .proto file, understands the service's business logic failure modes (e.g., NotFound for missing resources, InvalidArgument for bad input, PermissionDenied for unauthorized access), and can provide examples of how these errors are surfaced in code. This prompt is not a substitute for integration tests that verify the actual business logic; it is a contract test for the error-handling layer. Do not use this prompt when you lack a clear mapping between domain errors and status codes, when the service is a black box with no error documentation, or when you need to test transient network failures rather than application-level error semantics.

The primary constraint is that the generated tests are only as good as the error-mapping specification you provide. If the spec is ambiguous or incomplete, the prompt will produce plausible but potentially incorrect test cases. Always review the generated test scenarios against the actual service implementation and error-handling code. For high-reliability services, pair this prompt with a human review step and integrate the output into a CI pipeline that runs against a test instance before deployment.

This prompt template generates test cases that validate the correct mapping of domain-level errors to gRPC status codes. It is designed to be wired into a test generation pipeline where a protobuf service definition and a domain error catalog are available. The template forces the model to produce structured test cases with explicit preconditions, trigger actions, expected status codes, and metadata propagation checks. Use this when you need to ensure that internal errors surface to clients with the correct gRPC semantics and that no sensitive information leaks through error details.

Below is the copy-ready prompt template. Replace each square-bracket placeholder with the relevant input before sending it to the model. The placeholders are designed to be filled by an upstream system—such as a proto parser, an error registry, or a test harness configuration file—so that the prompt can be reused across multiple services without manual editing.

textCopy
You are a gRPC test engineer generating error code mapping test cases.

## INPUT
Service definition (protobuf):
[PROTO_SERVICE_DEFINITION]

Domain error catalog:
[DOMAIN_ERROR_CATALOG]

## CONSTRAINTS
- Generate exactly [TEST_CASE_COUNT] test cases.
- Each test case must target a single RPC method and a single domain error condition.
- Include both unary and streaming RPCs if present in the service definition.
- For each test case, specify the expected gRPC status code, expected status message substring, and expected metadata key-value pairs.
- Do not invent domain errors that are not in the catalog.
- Flag any domain error in the catalog that has no corresponding test case as an untested gap.

## OUTPUT SCHEMA
Return a JSON array of test case objects with this structure:
{
  "test_cases": [
    {
      "test_id": "string",
      "rpc_method": "string",
      "domain_error_triggered": "string",
      "preconditions": "string",
      "trigger_action": "string",
      "expected_grpc_status_code": "string (e.g., INVALID_ARGUMENT, NOT_FOUND, INTERNAL)",
      "expected_status_message_contains": "string",
      "expected_metadata": [{"key": "string", "value": "string"}],
      "streaming_type": "unary | client_stream | server_stream | bidi",
      "notes": "string"
    }
  ],
  "untested_gap_errors": ["string"]
}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, start by replacing [PROTO_SERVICE_DEFINITION] with the full protobuf service definition, including all RPC signatures and message types. Replace [DOMAIN_ERROR_CATALOG] with a structured list of domain error names, their descriptions, and the conditions under which they are raised. Set [TEST_CASE_COUNT] to a number that covers each domain error at least once, plus boundary conditions like deadline exceeded or cancellation. Provide [FEW_SHOT_EXAMPLES] that match your team's test case format and naming conventions. Set [RISK_LEVEL] to high if the service handles payments, health data, or authentication, which will trigger additional validation checks in the downstream harness. After generating the test cases, always run them through a schema validator that checks the JSON structure, status code validity against the gRPC code enumeration, and metadata key format compliance. For high-risk services, require a human reviewer to sign off on the mapping before the test cases are committed to the test suite.

This prompt is designed to be called programmatically from a test generation service or CI/CD step, not used as a one-off chat. The harness should supply the protobuf service definition, the domain error catalog, and the expected output schema as structured inputs. The model's response must be validated before any generated test code is committed or executed. Treat the prompt output as a test plan draft that requires deterministic verification against the actual gRPC service contract.

The implementation loop follows a clear sequence: (1) assemble the prompt with the service's .proto file content in [PROTO_DEFINITION] and the domain error-to-gRPC mapping table in [DOMAIN_ERROR_MAP]; (2) call the model with a low temperature (0.0–0.2) and request structured JSON output matching [OUTPUT_SCHEMA]; (3) run a post-generation validator that checks every generated test case against the proto definition—confirming that each RPC method referenced exists, each status code is a valid gRPC code, and each metadata key is declared in the service contract; (4) if validation fails, retry once with the validator errors appended as [PREVIOUS_ERRORS]; (5) on success, serialize the test cases into your target test framework (e.g., a pytest fixture or a Go table-driven test file). Log every generation attempt, the validator results, and the final test count for observability.

For CI/CD integration, gate the pipeline on validator pass/fail. If the validator rejects the output after the retry, fail the build and surface the specific schema violations to the team. Do not silently skip malformed test cases. In high-assurance environments, add a human review step before the generated tests are merged: a QA engineer should confirm that the error code mappings match the service's actual error-handling logic, especially for custom domain errors that the model may misinterpret. Avoid wiring this prompt directly to auto-commit without review when the service handles payments, health data, or access control.