Guidance on setting up basic functional tests

[dafeder]

Hi, I'm excited to have found this library as I've been thinking about building a PHP contract testing library for a while but this appears to share most of the same goals. But despite having read your docs and many of the issues in the queue I'm not quite getting it.

I have a working spec generated dynamically from my application, which is powering a basic Swagger UI page. On the swagger UI there are examples for essentially every parameters and request body, so if you try out any of the endpoints in the UI, whatever the default values are there they will usually produce a successful result if you hit "execute."

I have been hoping to, with a minimum of code, basically just have PHPUnit try each of the tests you can do manually in the SwaggerUI and assert the result matches expected. So, for example, here is one of my paths:

{
  "paths": {
    "/api/1/metastore/schemas/{schema_id}": {
      "get": {
        "operationId": "metastore-get-schema",
        "summary": "Get a specific schema",
        "tags": [
          "Metastore"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/schemaId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "description": "A schema definition, see https://json-schema.org/",
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Schema not found"
          }
        }
      }
    }
  }
}

And here is that parameter:

{
  "components": {
    "parameters": {
      "schemaId": {
        "name": "schema_id",
        "in": "path",
        "description": "The name a of a specific schema. For instance, \"dataset.\"",
        "schema": {
          "type": "string",
          "example": "dataset"
        },
        "required": true,
        "allowEmptyValue": false,
        "examples": {
          "dataset": {
            "value": "dataset"
          },
          "publisher": {
            "value": "publisher"
          },
          "distribution": {
            "value": "distribution"
          },
          "theme": {
            "value": "theme"
          },
          "keyword": {
            "value": "keyword"
          }
        }
      }
    }
  }
}

I've tried this to test it:

  public function testApiGet() {

    $request = new ApiRequester();
    $request
      ->withMethod('GET')
      ->withPath("/api/1/metastore/schemas/{schema_id}");
    $this->assertRequest($request);
  }

I get the error:

1) Drupal\Tests\common\Functional\ApiContractTest::testApiGet
ByJG\ApiTools\Exception\StatusCodeNotMatchedException: Status code not matched: Expected 200, got 404 ->
{
    "message": "Schema {schema_id} not found."
}

Looks like it doesn't automatically plug in the examples in the spec, which is fine, but if I try a path with the path parameter filled in, I get an error I don't really understand:

  public function testApiGet() {

    $request = new ApiRequester();
    $request
      ->withMethod('GET')
      ->withPath("/api/1/metastore/schemas/theme");
    $this->assertRequest($request);
  }

1) Drupal\Tests\common\Functional\ApiContractTest::testApiGet
ByJG\ApiTools\Exception\GenericSwaggerException: Not all cases are defined. Please open an issue about this. Schema: GET 200 /api/1/metastore/schemas/theme

I think I'm pretty close and if I understood what I need to be adding to give the request and assertion everything they need, I could test my whole spec with a minimum of code in my test class, but hoping you can provide a little guidance. Happy to contribute to the docs if that's helpful once I'm a little clearer on the usage, and may publish a helper library if I get this working and find a way to abstract some of these things in a repeatable way.