tcases:api-test

Full name:

org.cornutum.tcases:tcases-maven-plugin:4.0.5:api-test

Description:

Generates executable test code for API servers, based on an OpenAPI v3 compliant API definition. For full details on the Tcases for OpenAPI - what it does and how it works - see Tcases for OpenAPI: From REST-ful to Test-ful.

Attributes:

  • Requires a Maven project to be executed.

Optional Parameters

Name Type Since Description
<apiDef> String - Defines a single pattern that matches the OpenAPI definition files read by Tcases for OpenAPI, relative to the directory specified by the inputDir. If omitted, the default value matches all files of the form "*.json", "*.yaml", or "*.yml".
User property is: apiDef.
<apiDefs> Set - Defines a set of patterns that match the OpenAPI definition files read by Tcases for OpenAPI. By default, Tcases for OpenAPI uses the single pattern defined by the apiDef parameter.
User property is: apiDefs.
<baseClass> String - If defined, specifies a base class for the generated test class. This can be a fully-qualified class name or a simple class name, if the base class belongs to the same package as the generated test class.
User property is: baseClass.
<baseUri> String - If defined, specifies the base URI for the API server used by the generated tests. The value is an expression of one the following forms. If omitted, the default is "index=0".
  • index=<integer>

    From the servers array defined in the OpenAPI definition, use the URI of the given element.

  • contains=<text>

    From the servers array defined in the OpenAPI definition, use the URI of the first element with a description containing the given text.

  • uri=<uri>

    Use the specified <uri>.


Default value is: index=0.
User property is: baseUri.
<byPath> boolean - If true, a separate test file is generated for each of the API resource paths specified by the paths option, each containing tests for a single path. Otherwise, a single test file is generated containing tests for all paths.
Default value is: false.
User property is: byPath.
<contentType> String - Defines the default content type for API definition files. The contentType must be one of "json" or "yaml". The default content type is assumed for any file that is not specified explicitly or that does not have a recognized extension. If omitted, the default content type is "json".
User property is: contentType.
<execType> String - Defines the request execution interface used to run API tests. Valid values are "restassured".
Default value is: restassured.
User property is: execType.
<inputDir> String - Defines the path to the directory where OpenAPI definition files are located. A relative path is applied relative to the ${basedir} of the project.
Default value is: ${basedir}/src/test/tcases/openapi.
User property is: inputDir.
<maxTries> int - Defines the maximum attempts made to resolve a request test case input value before reporting failure.
Default value is: 10000.
User property is: maxTries.
<mocoTestConfig> String - When the testType is "moco", specifies the Moco server test configuration file. A relative path is applied relative to the ${basedir} of the project.
User property is: mocoTestConfig.
<onModellingCondition> String - Defines how input modelling conditions are handled. Valid values are "log", "fail", or "ignore".
Default value is: log.
User property is: onModellingCondition.
<onResolverCondition> String - Defines how request case resolver conditions are handled. Valid values are "log", "fail", or "ignore".
Default value is: log.
User property is: onResolverCondition.
<operations> Set - If defined, tests are generated only for the specified HTTP methods. If omitted, tests are generated for all operations.
User property is: operations.
<outDir> String - Defines the path to the directory where generated tests are written. A relative path is applied relative to the ${project.build.directory} of the project.
Default value is: ${project.build.directory}/generated-test-sources/java.
User property is: outDir.
<paths> Set - If defined, tests are generated only for the specified API resource paths. If omitted, tests are generated for all resource paths.
User property is: paths.
<project> String - A short-hand form of the apiDefs parameter that makes it easier to select the OpenAPI definition for a specific project. Equivalent to setting apiDefs to ∗∗/${project}.json,∗∗/${project}.yaml,∗∗/${project}.yml.
User property is: project.
<random> Long - Defines the random number generator seed for request case resolution.
User property is: random.
<readOnlyEnforced> boolean - Defines if the API will strictly enforce the exclusion of "readOnly" properties from requests.
Default value is: false.
User property is: readOnlyEnforced.
<resourceDir> String - Defines the path to the directory where generated test resources are written. A relative path is applied relative to the specified outDir. If omitted, a default path is derived from the specified outDir. If the outDir path follows Maven conventions for a Java source directory, the default resource directory is be the corresponding "resources" directory. Otherwise, the default resource directory is the same as the outDir.
User property is: resourceDir.
<source> String - Defines the source of API input definitions. Valid values are "schemas", or "examples".
Default value is: schemas.
User property is: source.
<testName> String - Defines the name of the test class that is generated. This can be either a fully-qualified class name or a simple class name.
User property is: testName.
<testPackage> String - Defines the package for the test class that is generated. This can be omitted if the testName is a fully-qualified class name or if the package can be determined from the outDir.
User property is: testPackage.
<testType> String - Defines the test framework used to run API tests. Valid values are "junit", "testng", or "moco".
Default value is: junit.
User property is: testType.
<timeout> Long - Defines the maximum time (in milliseconds) to complete an individual test method. A test failure occurs if a method continues past this time limit. If omitted, no time limit is enforced.
User property is: timeout.
<trustServer> boolean - If true, generated HTTPS requests will connect to the API server without verifying the server certificate. Otherwise, by default, the API server must present a trusted certificate.
Default value is: false.
User property is: trustServer.
<withResources> boolean - If false, no test resource files are produced.
Default value is: true.
User property is: withResources.

Parameter Details

<apiDef>

Defines a single pattern that matches the OpenAPI definition files read by Tcases for OpenAPI, relative to the directory specified by the inputDir. If omitted, the default value matches all files of the form "*.json", "*.yaml", or "*.yml".
  • Type: java.lang.String
  • Required: No
  • User Property: apiDef

<apiDefs>

Defines a set of patterns that match the OpenAPI definition files read by Tcases for OpenAPI. By default, Tcases for OpenAPI uses the single pattern defined by the apiDef parameter.
  • Type: java.util.Set
  • Required: No
  • User Property: apiDefs

<baseClass>

If defined, specifies a base class for the generated test class. This can be a fully-qualified class name or a simple class name, if the base class belongs to the same package as the generated test class.
  • Type: java.lang.String
  • Required: No
  • User Property: baseClass

<baseUri>

If defined, specifies the base URI for the API server used by the generated tests. The value is an expression of one the following forms. If omitted, the default is "index=0".
  • index=<integer>

    From the servers array defined in the OpenAPI definition, use the URI of the given element.

  • contains=<text>

    From the servers array defined in the OpenAPI definition, use the URI of the first element with a description containing the given text.

  • uri=<uri>

    Use the specified <uri>.

  • Type: java.lang.String
  • Required: No
  • User Property: baseUri
  • Default: index=0

<byPath>

If true, a separate test file is generated for each of the API resource paths specified by the paths option, each containing tests for a single path. Otherwise, a single test file is generated containing tests for all paths.
  • Type: boolean
  • Required: No
  • User Property: byPath
  • Default: false

<contentType>

Defines the default content type for API definition files. The contentType must be one of "json" or "yaml". The default content type is assumed for any file that is not specified explicitly or that does not have a recognized extension. If omitted, the default content type is "json".
  • Type: java.lang.String
  • Required: No
  • User Property: contentType

<execType>

Defines the request execution interface used to run API tests. Valid values are "restassured".
  • Type: java.lang.String
  • Required: No
  • User Property: execType
  • Default: restassured

<inputDir>

Defines the path to the directory where OpenAPI definition files are located. A relative path is applied relative to the ${basedir} of the project.
  • Type: java.lang.String
  • Required: No
  • User Property: inputDir
  • Default: ${basedir}/src/test/tcases/openapi

<maxTries>

Defines the maximum attempts made to resolve a request test case input value before reporting failure.
  • Type: int
  • Required: No
  • User Property: maxTries
  • Default: 10000

<mocoTestConfig>

When the testType is "moco", specifies the Moco server test configuration file. A relative path is applied relative to the ${basedir} of the project.
  • Type: java.lang.String
  • Required: No
  • User Property: mocoTestConfig

<onModellingCondition>

Defines how input modelling conditions are handled. Valid values are "log", "fail", or "ignore".
  • Type: java.lang.String
  • Required: No
  • User Property: onModellingCondition
  • Default: log

<onResolverCondition>

Defines how request case resolver conditions are handled. Valid values are "log", "fail", or "ignore".
  • Type: java.lang.String
  • Required: No
  • User Property: onResolverCondition
  • Default: log

<operations>

If defined, tests are generated only for the specified HTTP methods. If omitted, tests are generated for all operations.
  • Type: java.util.Set
  • Required: No
  • User Property: operations

<outDir>

Defines the path to the directory where generated tests are written. A relative path is applied relative to the ${project.build.directory} of the project.
  • Type: java.lang.String
  • Required: No
  • User Property: outDir
  • Default: ${project.build.directory}/generated-test-sources/java

<paths>

If defined, tests are generated only for the specified API resource paths. If omitted, tests are generated for all resource paths.
  • Type: java.util.Set
  • Required: No
  • User Property: paths

<project>

A short-hand form of the apiDefs parameter that makes it easier to select the OpenAPI definition for a specific project. Equivalent to setting apiDefs to ∗∗/${project}.json,∗∗/${project}.yaml,∗∗/${project}.yml.
  • Type: java.lang.String
  • Required: No
  • User Property: project

<random>

Defines the random number generator seed for request case resolution.
  • Type: java.lang.Long
  • Required: No
  • User Property: random

<readOnlyEnforced>

Defines if the API will strictly enforce the exclusion of "readOnly" properties from requests.
  • Type: boolean
  • Required: No
  • User Property: readOnlyEnforced
  • Default: false

<resourceDir>

Defines the path to the directory where generated test resources are written. A relative path is applied relative to the specified outDir. If omitted, a default path is derived from the specified outDir. If the outDir path follows Maven conventions for a Java source directory, the default resource directory is be the corresponding "resources" directory. Otherwise, the default resource directory is the same as the outDir.
  • Type: java.lang.String
  • Required: No
  • User Property: resourceDir

<source>

Defines the source of API input definitions. Valid values are "schemas", or "examples".
  • Type: java.lang.String
  • Required: No
  • User Property: source
  • Default: schemas

<testName>

Defines the name of the test class that is generated. This can be either a fully-qualified class name or a simple class name.
  • Type: java.lang.String
  • Required: No
  • User Property: testName

<testPackage>

Defines the package for the test class that is generated. This can be omitted if the testName is a fully-qualified class name or if the package can be determined from the outDir.
  • Type: java.lang.String
  • Required: No
  • User Property: testPackage

<testType>

Defines the test framework used to run API tests. Valid values are "junit", "testng", or "moco".
  • Type: java.lang.String
  • Required: No
  • User Property: testType
  • Default: junit

<timeout>

Defines the maximum time (in milliseconds) to complete an individual test method. A test failure occurs if a method continues past this time limit. If omitted, no time limit is enforced.
  • Type: java.lang.Long
  • Required: No
  • User Property: timeout

<trustServer>

If true, generated HTTPS requests will connect to the API server without verifying the server certificate. Otherwise, by default, the API server must present a trusted certificate.
  • Type: boolean
  • Required: No
  • User Property: trustServer
  • Default: false

<withResources>

If false, no test resource files are produced.
  • Type: boolean
  • Required: No
  • User Property: withResources
  • Default: true