verification_server.md

January 9, 2019 · View on GitHub

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:

call the test's endpoint from AutoDeserializeService, setting the index to the 0-indexed position of the test.
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:

call the test's endpoint from AutoDeserializeService, setting the index to the (number of positive tests) + the 0-indexed position of the negative test.
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.

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:

deserialize the test from the test cases JSON file.
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.

$ 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

verification_server.md