Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 5.72 KB

verification_server.md

File metadata and controls

117 lines (83 loc) · 5.72 KB

Verification server

This is a reference server used to test Conjure client generators and libraries.

master-test-cases.yml contains a variety of tests applicable to both verification client and verification server. To compile the verification-server test cases, run:

./gradlew compileTestCasesJson

That will generate a file /verification-server-api/build/test-cases.json, which conforms to this conjure-defined format.

Test type Service definition Comment
body auto-deserialize-service.conjure.yml See Body tests
single header single-header-service.conjure.yml Tests the ability to serialize a header param correctly. See Parameter tests.
single query param single-query-param-service.conjure.yml Tests the ability to serialize a query param correctly. See Parameter tests.
single path param single-path-param-service.conjure.yml Tests the ability to serialize a path param correctly. See Parameter tests.

Service definitions are generated into /verification-server-api/src/main/conjure/generated by running

./gradlew generate

Prerequisites

First, ensure the necessary artifacts are available in your testing environment:

Artifact Maven coordinate Classifier
verification-server.tgz com.palantir.conjure.verification:verification-server::${classifier}@tgz osx or linux
verification-server-test-cases.json com.palantir.conjure.verification:verification-server-test-cases
verification-server-api.conjure.json com.palantir.conjure.verification:verification-server-api

Workflow

The steps below mostly follow the RFC 004 workflow.

Body tests

These tests should verify two things, via the two services defined in auto-deserialize-service.conjure.yml:

  • response bodies are deserialized correctly (via AutoDeserializeService)
  • previously deserialized conjure values serialized correctly into request bodies (via AutoDeserializeConfirmService)

The tests include positive and negative tests for each endpoint.

The workflow for positive tests is:

  1. call the test's endpoint from AutoDeserializeService, setting the index to the 0-indexed position of the test.
  2. send the received value to the confirm endpoint from AutoDeserializeConfirmService using the same EndpointName and index.

Java example:

Object result = service.receiveDoubleExample(0);
service.confirm(EndpointName.of("receiveDoubleExample"), 0, result);

The workflow for negative tests is:

  1. call the test's endpoint from AutoDeserializeService, setting the index to the (number of positive tests) + the 0-indexed position of the negative test.
  2. assert than an exception was thrown because the body could not be deserialized.

Note: Because the tests in each endpoint have the same structure, if the language allows, it's simpler to generate the tests using reflection, rather than hand-rolling a new test for every endpoint.

Parameter tests

These tests verify that the client can deserialize a value, and is able to send it in a request, as either a path, query or header parameter. All of these tests are positive, i.e. they should all pass.

The workflow is:

  1. deserialize the test from the test cases JSON file.
  2. call the test's endpoint from the associated service for that parameter type, and pass it the deserialized value above.

Note: Because the parameter tests in each service & endpoint have the same structure, if the language allows, it's simpler to generate the tests using reflection, rather than hand-rolling a new test for every endpoint.

Ignoring failing tests

Please see the Partial Compliance section of RFC 004.

Example implementations

docker image

A docker image containing the server along with embedded test-cases.json and verification-server-api.conjure.json are published to: https://hub.docker.com/r/palantirtechnologies/conjure-verification-server/.

$ docker run -p 8000:8000 palantirtechnologies/conjure-verification-server:latest
Listening on http://0.0.0.0:8000

# in another terminal:
$ curl http://localhost:8000/receiveDoubleExample/0
{"value":1.23}
$ curl --data '{"value":1.23}' http://0.0.0.0:8000/confirm/receiveDoubleExample/0 -H 'Content-Type: application/json'
curl --data 'broken' http://0.0.0.0:8000/confirm/receiveDoubleExample/1 -H 'Content-Type: application/json'

Fox maximum logging, add -e RUST_LOG=debug to the docker run command.

Running the server locally

  • Ensure you've installed rustup as indicated in the Development section
  • Generate all test-cases.json and verification-server-api.json files 
    ./gradlew compileTestCasesJson compileIr
  • Start the server on http://0.0.0.0:8000 
    cargo run --package conjure-verification-server -- \
    verification-server-api/build/test-cases.json \
    verification-server-api/build/conjure-ir/verification-server-api.conjure.json