SoapUI Cookbook

You will learn the following topics:

You will need the following software:

The WSDL that we are going to use defines a simple invoice service. It has only one operation to retrieve a basic invoice document using its invoice number:

The WSDL can be found at soap/invoicev1/wsdl/invoice_v1.wsdl in this chapter's sample code.

We'll need the Apache CXF web service framework to generate the web service stub using SoapUI tooling. Download the latest version from http://cxf.apache.org/download.html (I have used version 3.01).

To build and run the service Java code, the minimum you will need is a suitable JDK. I have used JDK 1.7.0_25. Optionally, you may also want to use an IDE like Eclipse to make easy the work of exploring, building, and running the generated web service code.

First, we need to configure SoapUI to be able to generate and build the invoice web service. Then, we can run it as a standard Java executable. Perform the following steps:

To confirm whether it's actually working, open a browser and go to http://localhost:9001/ws/invoice/v1?wsdl, and you should see the (invoice_v1.wsdl) WSDL displayed. Our generated server is up and running.

All that SoapUI is actually doing is building command-line parameters for the various web service frameworks to do the generation. In this example, those happy with the command line could just run <Apache CXF Home>/bin/wsdl2java directly.

Let's take a quick look at the generated source files. The main points are as follows:

If the generated web service stub is to be used as the basis for on-going service development, then managing the generation, build, and deploy cycle externally to SoapUI using a build framework such as Ant, Maven, or Gradle will probably be a better option. To help with this, Apache CXF has a good Maven plugin to provide similar code generation; refer to http://cxf.apache.org/docs/maven-cxf-codegen-plugin-wsdl-to-java.html.

For those who want a quick and high-level way to generate a working web service for testing purposes, I would expect SoapUI's excellent mocking features to be a more convenient option than code generation in many cases (See Chapter 3, Developing and Deploying Dynamic REST and SOAP Mocks).

The SOAP web service stub journey will be continued in the next recipe when we add simple SoapUI tests and a basic implementation to pass them.

We'll need the WSDL from the previous recipe to set up our SoapUI project (<chapter1 samples>/soap/invoicev1/wsdl/invoice_v1.wsdl).

The Java code for the completed web service implementation can be found at <chapter1 samples>/soap/invoicev1_impl.

The project can be found at <chapter1 samples>/invoice-soap-v1-soapui-project.xml.

Firstly, we'll set up a couple of simple failing tests to assert what we expect back from the getInvoice operation and then provide basic implementation to pass them. Next, we'll update the invoice WSDL definition to provide an additional createInvoice operation, write new failing tests, and finally provide basic code to pass those. Perform the following steps:

Since we're dealing with SOAP XML, let's add 3 XPath Assertions to check these values in the response. SoapUI Pro users will find this easy, thanks to the convenient XPath builder. Open source users can either be 'hardcore' and write them from scratch or just copy the details provided.

So let's add 3 XPath Assertions. Edit the REST Request TestStep, under the Assertions tab and right-click on Add Assertion and add a new XPath Assertion to check the response's invoiceNo=12345, company=Test Company, and amount=100.0:

Have a look at the following screenshot for better clarity:

Running the TestCase should now fail 2 of the assertions. Note that InvoiceNoShouldBe12345 will work, thanks to Apache CXF passing through the request's invoiceNo to the response (see InvoicePortImpl.java)! It is still worth asserting the invoiceNo value, as it is a requirement.

Now, we can add a very basic service implementation to pass this test. We just need to implement the getInvoice(…) method in InvoicePortImpl.java. The simplest implementation option is to just edit InvoicePortTypeImpl.java and hardcode the expected values:

try {
    java.lang.String companyValue = "Test Company";
    company.value = companyValue;
    java.lang.Double amountValue = 100.0d;
    amount.value = amountValue;
} catch (java.lang.Exception ex) {
    ex.printStackTrace();
    throw new RuntimeException(ex);
}

Next, recompile this and restart the server:

cd <chapter1 samples>/soap/invoicev1
javac src/main/java/ws/invoice/v1/*.java -d target/classes/

And start it again:

cd <chapter1 samples>/soap/invoicev1/target/classes
java ws.invoice.v1.InvoicePortType_InvoicePort_Server

Rerun TestCase, which should now pass!

This recipe builds on all the same JAX-WS web service code explained in the previous recipe. This time, we add a very simple stub implementation to return the minimum necessary to pass the test. For those who haven't seen JAX-WS before, the use of the javax.xml.ws.Holder wrapper object means that we don't have to explicitly set the invoiceNo, as it is passed through the request (for more information, see http://tomee.apache.org/examples-trunk/webservice-holder/README.html).

As mentioned in the previous recipe, SoapUI mocks (see Chapter 3, Developing and Deploying Dynamic REST and SOAP Mocks) can often provide a convenient and often quicker alternative if all you need is a disposable test version of your web service with basic functionality. Also, if you want your web service stub to be the basis for ongoing development, then you may want to consider using a build framework like Gradle or Maven to manage the build, deploy, and test cycle. Chapter 5, Automation and Scripting, looks at different ways to use build frameworks and scripts to run SoapUI tests (and mocks) after your web service is built and deployed. If your stub implementations become more complicated, you may also want unit tests.

The SOAP web service stub journey continues in the next recipe where we use SoapUI to help us update the project, tests, and services to add a createInvoice operation.

The new WSDL defines a createInvoice operation and can be found in <chapter 1 samples>/soap/invoicev2_impl/wsdl/Invoice_v2.wsdl.

To save time coding the implementation, you can take either the full service code or just the Java classes you need from <chapter 1 samples>/soap/invoicev2_impl.

The SoapUI project for this recipe can be found at <chapter 1 samples>/invoice-soap-v2-soapui-project.xml.

After updating our SOAP project using the new WSDL and SoapUI's Update Definition functionality, we need to add a new failing test for the new createInvoice operation. Next, we generate an empty web service stub using the new WSDL and the approach shown in the first recipe. Finally, with our failing test, we will provide a basic implementation to pass the test.

The main learning of this recipe is how to use the Update Definition functionality, and what it does and doesn't update for you. Like in the previous recipe, we have only used a very basic service implementation just to pass the tests. The main points of the service implementation are as follows:

Here, we have developed a very simple non-persistent dynamic web service stub. Chapter 3, Developing and Deploying Dynamic REST and SOAP Mocks, also shows how to use in-memory H2 databases to provide a non-persistent, dynamic REST and SOAP mock service functionality. If you would like to persist the request data, then Chapter 9, Data-driven Load Testing With Custom Datasources, uses a SOAP service stub with a simple H2 database backend to persist data.

For Pro version users, the next recipe continues the SOAP web service stub journey by showing how SoapUI WSDL refactoring can help manage more complicated service definition updates.

We'll work on the <chapter1 samples>/invoice-soap-v2-soapui-project.xml project from the previous recipe. I have also included the project <chapter1 samples>/Invoice-soap-v3-soapui-project.xml, which is the end product after the refactoring.

The new WSDL can be found at <chapter1 samples>/soap/invoicev3/wsdl/invoice_v3.wsdl.

To illustrate the WSDL refactoring functionality, we'll refactor invoice_v2.wsdl and the tests from the previous recipe to use a new WSDL invoice_v3.wsdl. This will involve the following changes:

These changes will result in a CRUD style interface, with some basic schema changes:

On inspection of the refactored SoapUI project, all artifacts appeared to be in order, with the following exceptions:

The refactoring tool obviously doesn't write the missing tests for the updateInvoice and deleteInvoice operations or create Assertions for the new fields. These need to be added manually to return to an acceptable level of test coverage.

In terms of possible uses for WSDL refactoring, three typical SOA patterns are:

Variations on the first pattern are perhaps the most common, that is, refactoring of a single WSDL, as per our example. This is also the only pattern that can be covered in a single pass of the WSDL refactoring feature.

The example service is a REST version of the SOAP invoice service from the first recipe. The service is defined by a WADL with the following main properties:

Apache CXF will be used to generate, build, and run the stub web service. See the Getting ready section in the first recipe if you need advice on how to download Apache CXF.

The invoice-v1-soapui-project.xml project for this recipe can be found in the this chapter's sample code files.

First, we'll create a REST project from the service's WADL, and add a TestStep with Assertions to check whether the response's invoice values are what we expect. Then, we'll generate an empty runnable REST web service using Apache CXF, and finally add a simple implementation to pass the test. Perform the following steps:

Let's take a look at the main solution points:

Apart from using WADLs to create SoapUI projects for RESTful web services, there are also SoapUI plugins to use more modern alternatives such as RAML(http://raml.org/) and Swagger (http://swagger.io/) definitions as well—see Chapter 10, Using Plugins for more information.

To provide an example of a RESTful web service, I have extended the previous recipe's invoice service to have full CRUD functionality. The interface now looks like this:

Resource: http://localhost:9000/invoiceservice/v1/invoice 
Supported Methods:
POST   invoice      - Create Invoice. 
GET    invoice/{id} – Get (Read) Invoice.
PUT    invoice/{id} – Update Invoice.
DELETE invoice/{id} – Delete Invoice.

The invoice document is as follows:

{"Invoice": {
   "id": 12345,
"companyName": "Test Company",
"amount": 100
}}

The service's implementation is very basic. The create (POST) method is not idempotent, and it will create new invoice objects on each successful request with IDs of the form invN, where N is a sequence number that starts from 0, for example, inv0, inv1, and so on. The GET, UPDATE, and DELETE methods will all return HTTP status 404 if an invoice with the specified ID has not previously been created. The invoices are stored in a Java HashMap, so they will not persist when the server is restarted, and the HashMap is empty on startup.

Start the service in the same manner as described in the previous recipe:

cd <chapter1 samples>/chapter1/rest/invoice_crud/target/classes
java -cp "<apache-cxf-3.0.1 home>/lib/*:." rest.invoice.crud.v1.Server

To test its running, open a browser and go to http://localhost:9000/invoiceservice/v1?_wadl, and you should see a WADL displayed with methods as described in the preceding code.

The Mozilla Firefox browser is used to illustrate this recipe. Please download this if you don't already have it. If this isn't possible, other options will be described later.

Perform the following steps:

SoapUI sets up its own proxy to listen to all HTTP traffic routed through it. When you make a request through the REST client, SoapUI is able to extract the details and build up a list of sample requests. Then, when you have finished recording, SoapUI uses the list of requests to generate test artifacts in the same way it would if the requests had come from another source, for example, a WADL.

On inspection of the generated REST project, we can see that the REST discovery has provided a useful means of harvesting sample requests from a readymade service. You still need to create Assertions and perhaps organize the generated TestSteps. The REST discovery functionality could be useful when it comes to retrofitting tests, perhaps around a service that has been developed code-first, as in the above example. It could also be especially useful for services that don't present a WADL or similar definition and therefore cannot have test requests generated by other SoapUI means.