Merge pull request #97 from hasLeland/integration-readme-update

Update integration test readme

cmd/_integration-tests/README.md

@@ -1,27 +1,35 @@
 # integration-tests
 
 These tests run truss against definition files and tests if the generated code
-behaves. 
+behaves. Each test imports and uses service code generated by `truss`, but that
+code doesn't exist by default and must be generated before each test runs.
 
-# ./http
+# ./transport
 
-The `http` directory contains tests for the generated HTTP client libraries and
-standard Go `net/http` requests.
+The `transport` directory contains tests for ensuring the generated HTTP client
+libraries and the generated gRPC client libraries all correctly communicate
+over their particular transport. Additionally, there are tests using the
+standard standard Go `net/http` module to ensure that HTTP transport operates
+in a sane way, even for requests not made with the generated HTTP client.
 
 The test harness works as follows:
 
-- Runs truss against `http/httptest.proto`
-- Copy `http/handlers` into `http/handlers/httptest-service`
+- Runs truss against `transport/transport-test.proto`, which generates `transport/transport-service`
+- Copy `transport/handlers` into `transport/transport-service`
 - Run `go test -v`
-- Runs truss again against `http/httptest.proto` (for regeneration tests)
+- Runs truss again against `transport/transport-test.proto` (for regeneration tests)
 - Run `go test -v`
 
-`http/handlers` has implemented handlers for the server. They add things
-together for the purposes of testing.
+`transport/handlers` has implemented handlers for the server. These test
+handlers implement some very basic functionality for the purposes of testing.
+This functionality is to 'add' various things together; concatenating two
+strings and returning the concatenated string, or adding two numbers together
+and returning the addition.
 
-`http_test.go` imports the generated code, starts up a `httptest` server with
-the service HTTP handler, and then runs requests against this server, checking
-for errors and that the inputted values add to the outputted value.
+`transport/setup_test.go` sets up HTTP and gRPC servers with the methods for
+the test. Then each `transport/{TRANSPORT}_test.go` imports the generated code,
+runs requests against the server, checking for errors and that the input values
+add to the expected output value(s).
 
 # ./cli
 
@@ -29,12 +37,11 @@ The truss cli integration runner does the following tasks:
 
 - Runs truss on each service definition in `cli/test_service_definitions`
 - Builds the server and cliclient for each service
-- Runs the server
-- Runs the cliclient against the server
+- Runs the generated server
+- Runs the generated cliclient against the generated server
 - Passes if the server and cliclient were able to communicate. Fails if there
   were errors of any kind.
 
-*Test service definition requirements*
+Note also that any additional cli integration tests must have a package name
+`TEST`, all letters uppercase.
 
-Each service definition must have the package name `TEST`, all letters
-uppercase.