Tests to build

[sjparsons]

The document included in this PR proposes a beginning set of tests based on the current draft spec that can be implemented. All comments are welcome as we start to evolve this list. Especially things that I have not yet included.

#69

[sungam3r]

For syntax error spec now allows only 4xx and 5xx error codes
https://github.com/APIs-guru/graphql-over-http#status-codes

[sjparsons]

That's a good point. I feel conflicted over this since I think the spec should probably be more permissive on this point. But my concern is better to raise on the main spec, than here.

[sungam3r]

The point is that 200 may be returned only when GraphQL execution actually started. Otherwise there is no "GraphQL context". Syntax error or other errors before execution should return 4xx or 5xx.

[benjie]

A little editorial; I've tried to be strict with the MUST/MUST NOT/MAY/MAY NOT/SHOULD/SHOULD NOT.

[benjie]

Suggested change

	A 200 response should include a body. The body should include at least a `data` attribute or an `errors` attribute.
	A 200 response MUST include a body. If the body has `Content-Type` of `application/json`, `application/graphql` or `application/graphql+json`, the body MUST be a JSON object that conforms to the ["Response Format" as specified in the GraphQL Specification](https://spec.graphql.org/June2018/#sec-Response-Format).

[spawnia]

I think application/graphql is not meant to be used for responses, only for requests. It makes sense when sending a raw query string like so:

curl -v -H "Content-Type: application/graphql" -d "{ hello }"  "localhost:3000/graphql"

It might be a valid response header, but not to represent the result of a GraphQL operation. I guess it could be used for something like a schema/query generator.

[sjparsons]

I believe the content-type application/graphql+json can refer to a GraphQL JSON response document and the GraphQL request body. In other words, I think it should be a JSON document containing at least one of data or errors as top level attributes in a response.

When sending a POST request, a client should send application/graphql+json in the general case because they are also sending a JSON document, this time including a query, operationName and variables as the top-level attributes. The GraphQL query itself, which is found in this object (in the case of a POST request) at the query parameter should conform to the GraphQL specification.

I'm not clear on whether application/graphql is a synonym for application/graphql+json. Hypothetically, application/graphql could be distinct and refer to a valid GraphQL document string. However, we then would not be able to use it in GraphQL over HTTP since at no time do we send only a GraphQL query string to a server or receive only a GraphQL query string from a server.

[benjie]

Suggested change

	Server may response with non-200 status codes
	Server MUST NOT respond with any status code between 205 and 299 inclusive, or status codes 201, 202 or 203.
	Server MUST respond with a 200 status code if the GraphQL request has been executed [as defined in "Executing Operations" in the GraphQL Specification](https://spec.graphql.org/June2018/#sec-Executing-Operations). Server MAY respond with a 204 status code if appropriate according to RFC7231.
	Server MAY respond with non-200 status codes if the GraphQL request is invalid, or if the server is unable to process it.

[sjparsons]

We need to put this language in the spec first and then let the test cases fall out from that. Could this be made as a proposal on #79?

[sjparsons]

I've made some substantial changes to take into account most of the feedback. Some of this has resulted in another PR since I think some of the great suggestions here are spec-worthy, not just relevant for our tests.

I've also increased the clarity of the difference between ERROR and WARNING assertion failures. Hopefully those can be worked into our tests.