Skip to content

README.md

Latest commit

 

History

History
168 lines (128 loc) · 6.27 KB

README.md

File metadata and controls

168 lines (128 loc) · 6.27 KB

Request/Response Adapters Lab

Objective

If a client fails against a spec-driven mock, it usually means there is a mismatch between the client's request/response and the provider's expected request/response format. This lab will help you understand how to identify such mismatches and use Specmatic's data adapter to temporarily adapt the provider service's interface to match the consumer's expected interface. This allows you to continue development and testing without waiting for the provider to fix their specification, while still ensuring that your expectations are valid against the specification.

Time required to complete this lab

10-15 minutes.

Prerequisites

  • Docker is installed and running.
  • You are in labs/data-adapters.

Architecture

  • camel-case-service (Specmatic mock): serves the contract from .specmatic/repos/labs-contracts/openapi/data-adapters/camelCase.yaml on http://127.0.0.1:9090
  • ui service (Nginx): serves a small web page on http://127.0.0.1:8080
  • Browser UI sends a PascalCase request to camel-case-service, which expects request in camelCase

Files in this lab

  • .specmatic/repos/labs-contracts/openapi/data-adapters/camelCase.yaml: Provider contract used by specmatic.yaml to start the mock service after the contracts repo is checked out.
  • specmatic.yaml: Specmatic configuration.
  • ui/index.html: Simple UI that sends PascalCase query/header/body fields.
  • ui/default.conf: Nginx config that serves UI and proxies /test to the mock.
  • hooks/pre_specmatic_request_processor.sh: Converts outgoing request keys from PascalCase to camelCase.
  • hooks/post_specmatic_response_processor.sh: Converts incoming response keys from camelCase to PascalCase.

Reference

Lab Rules

  • Do not edit the spec in .specmatic/repos/labs-contracts/openapi/data-adapters/camelCase.yaml.
  • Do not change docker-compose.yaml.
  • Do not touch the ui/index.html.
  • Fix the mismatch only by wiring the existing hook scripts in specmatic.yaml.

1. Start mock + UI

Run:

docker compose up

2. Trigger the mismatch from browser (intentional failure)

  1. Open http://127.0.0.1:8080.
  2. Keep default values and click Submit button.
  3. Observe a 400 bad-request response in the result panel.

You can verify the same failure directly against the service running on 9090:

docker compose --profile test run --rm verifier
HTTP/1.1 400 Bad Request

Expected result:

  • The response status should be 400 Bad Request.
  • This confirms that, before adapters are configured, the service on 9090 rejects the PascalCase request because the service expects camelCase fields.

Why it fails:

  • The UI sends PascalCase fields (RequestQuery, RequestHeader, RequestKey).
  • The provider service (mock in our case) expects camelCase fields (requestQuery, requestHeader, requestKey).

This fail-first behavior is expected in this lab.

3. Cleanup

Run:

docker compose down -v

4. Configure hooks in specmatic.yaml

Add the following data block under dependencies in specmatic.yaml so that it sits alongside services:

dependencies:
  services:
    # existing service config
  data:
    adapters:
      pre_specmatic_request_processor: ./hooks/pre_specmatic_request_processor.sh
      post_specmatic_response_processor: ./hooks/post_specmatic_response_processor.sh

Why both hooks are needed:

  • pre_specmatic_request_processor: adapts PascalCase request fields to camelCase before sending to mock.
  • post_specmatic_response_processor: adapts camelCase mock response fields back to PascalCase before assertion.

5. Ensure hook scripts are executable

Run:

chmod +x hooks/pre_specmatic_request_processor.sh hooks/post_specmatic_response_processor.sh

6. Restart mock + UI

Run:

docker compose up

7. Trigger the matching request/response from browser

  1. Open http://127.0.0.1:8080.
  2. Keep default values and click Submit button.
  3. Observe a 200 response in the result panel.

8. Verify the service call directly via Curl

Run:

docker compose --profile test run --rm verifier
HTTP/1.1 200 OK

Expected result:

  • The response status should be 200 OK.
  • The response should include the adapted response fields, showing that the mock on 9090 is now accepting the PascalCase request and returning a successful response through the configured adapters.

9. Cleanup

Run:

docker compose down -v

Windows Notes

  • If you use PowerShell or CMD, chmod may not work. Use Git Bash for this step, or run:
git update-index --chmod=+x hooks/pre_specmatic_request_processor.sh hooks/post_specmatic_response_processor.sh
  • Ensure hook files use LF line endings (not CRLF). In Git Bash:
sed -i 's/\r$//' hooks/pre_specmatic_request_processor.sh hooks/post_specmatic_response_processor.sh
  • If the test still fails with the same RequestQuery/requestQuery mismatch after adding adapters, it usually means hook scripts were not executed. Re-check execute bit and LF line endings.

10. Verify in Studio (Optional)

Start Studio:

docker compose --profile studio up -d studio ui
  1. Open http://127.0.0.1:9000/_specmatic/studio,
  2. Open specmatic.yaml, run the suite or start the mock from the Mock tab, and use port 9090. If you want to inspect the contract file in Studio, open .specmatic/repos/labs-contracts/openapi/data-adapters/camelCase.yaml from the left panel after the repo is checked out.
  3. Open http://127.0.0.1:8080.
  4. Keep default values and click Submit button.
  5. Observe a 200 response in the result panel.
  6. Go to the Mock tab and look at the request and response payloads. You should see how the data adapters have transformed the field names in both directions.

11. Cleanup

Run:

docker compose --profile studio down -v

Next step

If you are doing this lab as part of an eLearning course, return to the eLearning site and continue with the next module.