Release 3.4.0 (#114)

HowToDownload.md

@@ -8,6 +8,7 @@ To get the command line version of Tcases, download the Tcases binary distributi
   1. Search for "tcases-shell".
   1. You will see the most recent release of `tcases-shell`. (To see all N previous versions, select `(N)` under "Latest Version".)
   1. Use the :arrow_down: button to select the type of file you want to download. Choose either a ZIP file or a compressed tar file (tar.gz).
+  1. See *The Complete Guide* for [tips on installation](http://www.cornutum.org/tcases/docs/Tcases-Guide.htm#install).
 
 
 ## Tcases Libraries
@@ -62,6 +63,32 @@ The core models for Tcases objects. For the current version, see the [release no
 </dependency>
 ```
 
+#### tcases-rest-assured
+(Since 3.4.0) Provides a [`TestCaseWriter`](http://www.cornutum.org/tcases/docs/api/org/cornutum/tcases/openapi/restassured/RestAssuredTestCaseWriter.html)
+implementation for [REST Assured](https://github.com/rest-assured/rest-assured).
+For the current version, see the [release notes](ReleaseNotes.md).
+
+```xml
+<dependency>
+  <groupId>org.cornutum.tcases</groupId>
+  <artifactId>tcases-rest-assured</artifactId>
+  <version>...</version>
+</dependency>
+```
+
+#### tcases-moco
+(Since 3.4.0) Provides a [`TestWriter`](http://www.cornutum.org/tcases/docs/api/org/cornutum/tcases/openapi/moco/MocoServerTestWriter.html)
+implementation for JUnit API tests using a [Moco](https://github.com/dreamhead/moco) stub server.
+For the current version, see the [release notes](ReleaseNotes.md).
+
+```xml
+<dependency>
+  <groupId>org.cornutum.tcases</groupId>
+  <artifactId>tcases-moco</artifactId>
+  <version>...</version>
+</dependency>
+```
+
 #### tcases-ant
 (Since 2.0.0) Provides an Ant task for running Tcases. For the current version, see the [release notes](ReleaseNotes.md).
 

README.md

@@ -2,10 +2,11 @@
 
 ## What's New? ##
 
-  * The latest version ([Tcases 3.3.0](ReleaseNotes.md#330)) is now available at the Maven Central Repository.
-    See [HowToDownload](HowToDownload.md) for download instructions.
+  * The latest version ([Tcases 3.4.0](ReleaseNotes.md#340)) is now available at the Maven Central Repository.
+    See [*How To Download Tcases*](HowToDownload.md) for download instructions.
 
-  * Tcases 3.3.0 delivers significant improvements to Tcases for OpenAPI. See the [release notes](ReleaseNotes.md#330) for details.
+  * Tcases 3.4.0 introduces an important new capability for Tcases for OpenAPI: generating an executable test directly from an OpenAPI v3 spec.
+    See the [release notes](ReleaseNotes.md#340) for details.
 
   * Subscribe to the [Tcases Forum](https://groups.google.com/d/forum/tcases) group to get notifications and share experiences with other Tcases users.
 

ReleaseNotes.md

@@ -1,5 +1,34 @@
 # Release Notes #
 
+## 3.4.0 ##
+
+This release introduces an important new capability for Tcases for OpenAPI: generating an executable test directly from an OpenAPI v3 spec.
+You can do this from the command line, using the new `tcases-api-test` command, or with the
+[Tcases Maven Plugin](http://www.cornutum.org/tcases/docs/tcases-maven-plugin/), using the new `tcases:api-test` goal. For this release,
+these commands can automatically create Java tests, runnable with either JUnit or TestNG, that execute all requests using the REST Assured DSL.
+For all the details, see [*Running API Test Cases*](tcases-openapi/Running-Api-Test-Cases.md#running-api-test-cases).
+
+Other improvements:
+
+  * **Tcases for OpenAPI**
+    * For request parameters containing a `string` value, the string `format` may limit the range of valid lengths. Generated
+      input models now recognize such `format` constraints, and generated test cases cover both valid and invalid lengths.
+
+    * For request parameters containing a `string` value, input resolution now produces strings that conform to the character set restrictions
+      for the location specified by the parameter `in` property.
+
+    * Input resolution now correctly handles failure test cases for invalid `readOnly` properties in request inputs.
+
+    * A new number format is used in generated identifiers. Some values in an OpenAPI spec must be converted into identifiers -- for example,
+      to designate input variables in the generated input model or Java methods in generated test code. In the new identifier format,
+      numeric values are converted by replacing '-' with 'm' and replacing '.' with 'd'. For example, converting "-123.45" will
+      now produce the identifier "m123d45".
+
+  * **Tcases Core**
+    * `TestCase` now has an optional `name` property that provides a descriptive name for the test case. For `TestCase` instances
+       generated by Tcases, the `name` is a description of the tuple that this test case was created to cover.
+
+
 ## 3.3.0 ##
 
 This release delivers significant improvements to Tcases for OpenAPI.

pom.xml

@@ -7,7 +7,7 @@
   <groupId>org.cornutum.tcases</groupId>
   <artifactId>tcases</artifactId>
   <packaging>pom</packaging>
-  <version>3.3.1-SNAPSHOT</version>
+  <version>3.4.0</version>
 
   <name>Tcases</name>
   <description>Generates test cases from system input space models</description>

tcases-ant/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.cornutum.tcases</groupId>
     <artifactId>tcases</artifactId>
-    <version>3.3.1-SNAPSHOT</version>
+    <version>3.4.0</version>
   </parent>
 
   <artifactId>tcases-ant</artifactId>

tcases-cli/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.cornutum.tcases</groupId>
         <artifactId>tcases</artifactId>
-        <version>3.3.1-SNAPSHOT</version>
+        <version>3.4.0</version>
     </parent>
 
     <artifactId>tcases-cli</artifactId>

tcases-io/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.cornutum.tcases</groupId>
         <artifactId>tcases</artifactId>
-        <version>3.3.1-SNAPSHOT</version>
+        <version>3.4.0</version>
     </parent>
 
     <artifactId>tcases-io</artifactId>

tcases-lib/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.cornutum.tcases</groupId>
     <artifactId>tcases</artifactId>
-    <version>3.3.1-SNAPSHOT</version>
+    <version>3.4.0</version>
   </parent>
 
   <artifactId>tcases-lib</artifactId>

tcases-maven-plugin/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.cornutum.tcases</groupId>
     <artifactId>tcases</artifactId>
-    <version>3.3.1-SNAPSHOT</version>
+    <version>3.4.0</version>
   </parent>
 
   <artifactId>tcases-maven-plugin</artifactId>

tcases-maven-plugin/src/site/apt/index.apt

@@ -36,6 +36,8 @@ Tcases Plugin
 
   * {{{./api-mojo.html}tcases:api}} Runs {{{./usage.html#Running_Tcases_For_OpenAPI}Tcases for OpenAPI}}.
 
+  * {{{./api-test-mojo.html}tcases:api-test}} Runs Tcases for OpenAPI to {{{./usage.html#Generating_Executable_API_Tests}generate executable API tests}}.
+
 * Usage
 
   General instructions on how to use the Tcases Plugin can be found on the {{{./usage.html}usage page}}.  

tcases-maven-plugin/src/site/apt/usage.apt

@@ -523,6 +523,9 @@ mvn tcases:tcases -DdefaultTupleSize=2
   generates test cases for your API directly from an OpenAPI v3 specification. To
   run it, use the {{{./api-mojo.html}tcases:api}} goal.
 
+  You can even translate an OpenAPI v3 specification directly into an {{{Generating_Executable_API_Tests} executable test program}},
+  using the {{{./api-test-mojo.html}tcases:api-test}} goal.
+
 ** {Generating API Test Cases}
 
   Let's assume you are using the default configuration for <<<tcases:api>>>. Suppose you have an OpenAPI spec
@@ -556,6 +559,24 @@ mvn tcases:api
 mvn tcases:api -Dproject=My-API
 +--------
 
+** {Generating Executable API Tests}
+
+  Let's assume you are using the default configuration for <<<tcases:api>>>. Suppose you have an OpenAPI spec
+  named <<<$\{basedir\}/src/test/tcases/openapi/org/myapp/My-API.yaml>>> 
+
+  What happens when you run the following command, this time using the {{{./api-test-mojo.html}api-test}} goal
+
++--------
+mvn tcases:api-test -Dproject=My-API 
++--------
+
+  Congratulations! You just created a new JUnit test for your API! You'll find the source for the new
+  test class in <<<$\{basedir\}/target/generated-test-sources/java/org/myapp/MyApiTest.java>>>.
+  Build and execute this test to run all test cases for every requests defined in <<<My-API.yaml>>>.
+
+  How was this test constructed? And what does it really do? For answers, see
+  {{{https://github.com/Cornutum/tcases/blob/master/tcases-openapi/Running-Api-Test-Cases.md#generating-executable-tests}Generating executable tests}}.
+
 ** {Generating Request Inputs}
 
   Let's assume you are using the default configuration for <<<tcases:api>>>. Suppose you have an OpenAPI spec

tcases-moco/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.cornutum.tcases</groupId>
         <artifactId>tcases</artifactId>
-        <version>3.3.1-SNAPSHOT</version>
+        <version>3.4.0</version>
     </parent>
 
     <artifactId>tcases-moco</artifactId>

tcases-openapi/README.md

@@ -163,12 +163,8 @@ Ideally, Tcases for OpenAPI would produce a test program that you could immediat
 execute all API requests against an actual API server, applying a comprehensive set of request input data and automatically verifying
 the expected responses. Bam! Job done!
 
-Unfortunately, that is not possible -- you have to construct at least some of this test program yourself.
-But fortunately, Tcases for OpenAPI provides options to automate some of the process. For details, see
-[*Running API Test Cases*](Running-Api-Test-Cases.md).
-
-Although it's still up to you complete this test program, Tcases for OpenAPI gives you a lot to work with. Think of it as detailed
-guidance on how to use a fairly small number of test cases to gain [high confidence in your API](#want-high-confidence-in-your-api).
+But is this even possible? Yes, it is -- mostly.
+For details, see [*Running API Test Cases*](Running-Api-Test-Cases.md).
 
 
 ## Why Tcases for OpenAPI? ##
@@ -396,6 +392,9 @@ which operate directly with the [Java API for OpenAPI](https://github.com/swagge
 classes are based on the [Tcases Core API](http://www.cornutum.org/tcases/docs/api/) for manipulating system and test
 models.
 
+Your Java application can even produce executable tests, using the [TestWriter API](Running-Api-Test-Cases.md#understanding-the-testwriter-api)
+for Tcases for OpenAPI.
+
 ## OpenAPI tips ##
 
 To use Tcases for OpenAPI effectively, there are some things to keep in mind when you're building your OpenAPI spec.

tcases-openapi/Request-Test-Definition.md

@@ -23,6 +23,8 @@ A `RequestCase` object defines the inputs for a test case that invokes a specifi
 | id            | integer | :registered:    | An id number that uniquely identifies this test case among all tests for the given path and operation |
 | path          | string | :registered:     | The request path |
 | operation     | string | :registered:     | The HTTP operation for this request |
+| api           | string | :registered:     | The title of the API that defines this request |
+| name          | string |                  | A descriptive name for this test case |
 | server        | string |                  | The API server URL |
 | version       | string |                  | The version of the OpenAPI spec that defines this request |
 | parameters    | \[[`ParamData`](#paramdata)\] |     | The parameter values for this request |