Adding a Unit Test to Your Service

This document summarises steps needed in order to add unit test cases to your Perl based SADI service.

SADI Service Support) will automatically insert any test cases that you define into your service signature for others to see!

At the end of this tutorial, you will have defined a test case for your service.

Test cases define the expected behaviour of your service based on a specified input. In SADI, you can check the expected behaviour by:

providing the expected output that your specified input generates, or
providing an XPATH expression that can be applied to the service output that was generated from your specified input, or
providing a regular expression that can be applied to the service output that was generated from your specified input.

Test cases that you create can either state all of the above items or any one of them.

This tutorial will generate a test case for the SADI service getGOTerm, that we created in a previous tutorial.

Let's now move on towards building our test case for our SADI service. In step 1 below, we will make sure that you have all of the dependencies in order.

Step 1: What is needed
Step 2: Service unit test generation
Step 3: Specifying service input
Step 4: Obtaining service output
Step 5: Updating your service registration

Step 1: What is needed

To create unit tests for SADI services using SADISeS, you need to have the following installed on your machine:

Perl - perl has to be installed on your machine

A web server - this document assumes that you are using Apache2

Perl SADI (version 0.99.5 or greater) - available on cpan

To implement this a test case for getGOTerm SADI service, you will need, in addition to the above requirements,

to have followed the tutorial that creates the sadi service getGOTerm.

Once you have installed Perl SADI and all of its dependencies on your machine, you will have to run through the SADISeS set up. This is only done once per user of SADISeS (unless you are upgrading Perl-SADISeS). For more information, please view the SADI::SADI documentation.

Step 2: Service unit test generation

Before we can specify a unit test, we need to tell SADISeS to generate a file that we can fill in with our information.

The service that we are going to write a unit test for in this document is one that given a GO record, will return the GO term name and GO term definition. This service implementation is described here!

To generate a unit test file for your service, issue the following command at the command prompt:

$ sadi-generate-services.pl -T getGOTerm

Basically, this tells SADISeS that we would like to generate a unit test for the service 'getGOTerm'. The generated file can be found in ~/Perl-SADI/unittest/getGOTerm.

If you open the generated unit test file, you will see something like the following:

# This is a SADI service unit test file
# uncomment the applicable lines to specify
# your unit test

# unit test for 'getGOTerm'
[unittest]
input = /home/ubuntu/Perl-SADI/xml/getGOTerm.xml
output = /home/ubuntu/Perl-SADI/xml/getGOTerm-output.xml
#regex = 
#xpath = 

#[unittest2]
# repeat the block above to add more tests

SADISeS has done a nice job in preparing this file for us!

Notice that SADISeS created some input and output file paths for us. As a best practice, input and output for your SADI services should be placed in the ~/Perl-SADI/xml directory.

We will be using the default file paths that SADISeS created for us in our unit test file.

Step 3: Specifying service input

Now that we have a unit test file, the next step in creating a test case is to specify the service input that we will test our service with!

Create a file ~/Perl-SADI/xml/getGOTerm.xml and put the following XML document in it:

<rdf:RDF
     xmlns="http://www.w3.org/2002/07/owl#"
     xml:base="http://bioinfo.icapture.ubc.ca/SADI"
     xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"

     xmlns:lsrn="http://purl.oclc.org/SADI/LSRN/"
     xmlns:owl="http://www.w3.org/2002/07/owl#"

     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   <lsrn:GO_Record rdf:about="http://biordf.net/moby/GO/0043116"/>

</rdf:RDF>

Once you have placed the text in the file, save it and proceed to the next step!

Step 4: Specifying service output

Now that we have specified the service input for our test case, we need to specify any or all of the following:

expected output,
an xpath expression to apply to the output of our service when given the specified input,
a regular expression to apply to the output of our service when given the specified input.

In this tutorial, we will be only specifying the expected output for our service.

The easiest way to obtain the expected output for our service is to run the service with our sample input and capture the output.

$ sadi-testing-service.pl Service::getGOTerm ~/Perl-SADI/xml/getGOTerm.xml

The output from the service:

<rdf:RDF
xmlns:a="http://sadiframework.org/ontologies/predicates.owl#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
>
<rdf:Description rdf:about="http://lsrn.org/GO:0043116">
<a:hasTermName>negative regulation of vascular permeability</a:hasTermName>
<a:hasTermDefinition>Any process that reduces the extent to which blood vessels can be pervaded by fluid.</a:hasTermDefinition>
</rdf:Description>
</rdf:RDF>

Create a file ~/Perl-SADI/xml/getGOTerm-output.xml and put the above XML text in it.

Once you have saved the above file, you have successfully specified the expected output for your service.

Step 5: Updating your service registration

Having created a test case for our service, the next thing to do is to perform an HTTP get on our service to view the service signature. Assuming that we did everything right, you should see our test case in the signature.

Finally, the next thing to do is to ensure that we update our service registration on http://sadiframework.org/registry/.