Karate Open Api Generator

Automatic generation of tests in Gherkin, with their related data sets and schemas for response validation as well as data to mock external services from Open Api definitions

Karate open-api-generator has the following generation modes:

  • Karate Operations: Generates operation feature files and validation schemas which will be shared for all tests for each of the Open API defined paths and methods.

    The operations are the base for the execution of all the tests, so this is a mandatory step which should be the first step of the generation process.

  • Karate Smoke Tests: Generates smoke tests for each of the Open API defined paths and response codes. These tests are meant only to verify the artifact end-points are compliant (response codes and schemas) with their Open API definition.

    • After the automatic generation the tests data files should be updated to fullfil the purpose of each scenario.

  • Karate Functional Test: Generates functional tests for the choosen combination of Open API paths and response codes. These tests are meant to verify the artifact end-points functionalities.

    • After the automatic generation the tests should be updated regarding:

      • operation steps order

      • test data

      • verification steps

      • (if applicable) include steps for initial data (jdbc, mongodb, kafka, jms) using the 🛠️ Karate Clients

      • (if applicable) include steps for additional checks (jdbc, mongodb, kafka, jms) using the 🛠️ Karate Clients

  • Karate Mock Data: Generates mock data for the choosen combination of Open API paths and response codes of external APIs. The mock data files are meant to be used by the karate mock server to simulate the behaviour of the external APIs.

    • After the automatic generation the mock data files should be updated regarding the corresponding path, params, request and response bodies to match needed mocking scenarios.

Configuration

If the project has been generated using the Karate Tools Archetype the pom will already contain the corresponding configuration.
Add the karatetools dependency and execution plugin in the karate pom: 
<properties>
  ...
  <!-- Karate Tools -->
  <karatetools.version>X.X.X</karatetools.version>
  <exec-maven-plugin.version>X.X.X</exec-maven-plugin.version>

  <!-- Configuration Properties -->
  <!-- Open Api OperationId Sanitize Mode -->
  <open-api-operation-id-sanitize.mode>alphanumeric</open-api-operation-id-sanitize.mode>
  ...
</properties>

<build>
  <plugins>
    <!-- Karate Tools - Generators -->
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>exec-maven-plugin</artifactId>
      <version>${exec-maven-plugin.version}</version>
      <executions>
        <!-- Karate Tools - Generators - OpenApi -->
        <execution>
          <id>open-api-generator</id>
          <goals>
            <goal>java</goal>
          </goals>
          <configuration>
            <mainClass>dev.inditex.karate.openapi.OpenApiGeneratorCLI</mainClass>
            <classpathScope>test</classpathScope>
            <includeProjectDependencies>false</includeProjectDependencies>
            <includePluginDependencies>true</includePluginDependencies>
            <cleanupDaemonThreads>false</cleanupDaemonThreads>
            <executableDependency>
              <groupId>dev.inditex.karate</groupId>
              <artifactId>karatetools-starter</artifactId>
            </executableDependency>
            <systemProperties>
              <systemProperty>
                <key>logback.configurationFile</key>
                <value>src/test/resources/logback-test.xml</value>
              </systemProperty>
              <systemProperty>
                <key>open-api-operation-id-sanitize.mode</key>
                <value>${open-api-operation-id-sanitize.mode}</value>
              </systemProperty>
            </systemProperties>
          </configuration>
        </execution>
      </executions>
      <dependencies>
        <dependency>
          <groupId>dev.inditex.karate </groupId>
          <artifactId>karatetools-starter</artifactId>
          <version>${karatetools.version}</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

Operation ID Sanitize Mode

The operationId sanitize mode controls how special characters in Open API operationId values are removed before generation.

It is configured via the open-api-operation-id-sanitize.mode Maven property, which is forwarded as a JVM system property to the generator.

Mode Description Example (get-user-V1)

alphanumeric (default)

Removes leading non-letter/non-underscore characters and any non-word characters. Preserves digits and underscores.

getuserV1

letters-only

Removes everything that is not a letter [a-zA-Z].

getuserV
Override the default permanently in your pom.xml <properties>, or at the command line per execution (see Open API Generator - Execution).
Configure open-api-operation-id-sanitize.mode in the karate pom: 
<properties>
  ...
  <!-- Configuration Properties -->
  <!-- Open Api OperationId Sanitize Mode -->
  <!-- override default (alphanumeric) -->
  <open-api-operation-id-sanitize.mode>letters-only</open-api-operation-id-sanitize.mode>
  ...
</properties>
...

<build>
  <plugins>
    <!-- Karate Tools - Generators -->
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>exec-maven-plugin</artifactId>
      <version>${exec-maven-plugin.version}</version>
      <executions>
        <!-- Karate Tools - Generators - OpenApi -->
        <execution>
          <id>open-api-generator</id>
          ...
          <configuration>
            <systemProperties>
              ...
              <systemProperty>
                <key>open-api-operation-id-sanitize.mode</key>
                <value>${open-api-operation-id-sanitize.mode}</value>
              </systemProperty>
            </systemProperties>
          </configuration>
        </execution>
      </executions>
      ...
    </plugin>
  </plugins>
</build>

API Dependencies

Include dependencies to project rest-api + Third Party APIs which need mocking in the karate pom.xml

<properties>
  ...
  <!-- APIs -->
  <xxx-api-rest-stable.version>X.X.X</xxx-api-rest-stable.version>
  <!-- Third Party APIs -->
  <xxx-external-api-rest-stable.version>X.X.X</xxx-external-api-rest-stable.version>
  ...
</properties>

<dependencies>
  ...
  <!-- APIs -->
  <dependency>
    <groupId>com.mypackage.api</groupId>
    <artifactId>xxx-api-rest-stable</artifactId>
    <version>${xxx-api-rest-stable.version}</version>
  </dependency>
  <!-- Third Party APIs -->
  <dependency>
    <groupId>com.mypackage.api</groupId>
    <artifactId>xxx-external-api-rest-stable</artifactId>
    <version>${xxx-external-api-rest-stable.version}</version>
  </dependency>
  ...
</dependencies>

Once the api dependencies are included in the pom, the Open API sources must be generated to be accessible for the open-api-generator, executing the command:

mvn generate-sources

The generated files openapi-rest.yml will be generated in folder target/apis/…​

For example:

\---target
    \---apis
        +---xxx-api-rest-stable-jar
        |       openapi-rest.yml
        |
        +---xxx-external-api-rest-stable-jar
        |       openapi-rest.yml
        |
        \---xxxx-rest-jar
            \---rest
                    openapi-rest.yml
open-api-generator also supports openapi-rest.yml files directly placed in some karate folder.

Execution

Execute open-api-generator and enter the requested inputs, starting by the generation mode.

mvn exec:java@open-api-generator
To override the operationId sanitize mode at generation time, pass the property on the command line (see Open API Generator - Configuration - Operation ID Sanitize Mode for available modes): 
mvn exec:java@open-api-generator -Dopen-api-operation-id-sanitize.mode=letters-only
Select generation mode using the up/down arrows ↑ ↓ and afterwards intro to proceed ↲ to next step. 
? Enter Open Api Generator Mode (Operations / Smoke Tests / Functional Test / Mock Data)
> Open Api Operations
  Open Api Smoke Tests
  Open Api Functional Test
  Open Api Mock Data
open api generator cmd operations

Once the generation mode has been selected you can proceed the chosen mode:

  1. Karate Open Api Generator - Operations

  2. Karate Open Api Generator - Smoke Tests

  3. Karate Open Api Generator - Functional Test

  4. Karate Open Api Generator - Mock Data