<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<link href="http://sadiframework.org/style/sadi.css" type="text/css" rel="stylesheet"/>
<style type="text/css">
h2 {
margin-top: 2em;
margin-left: 2em
}
h3 {
margin-top: 2em;
margin-left: 4em
}
h4 {
margin-top: 2em;
margin-left: 6em
}
p {
margin-left: 6em
}
pre {
margin-left: 8em;
margin-right: 8em;
padding: 4px;
font-family: monospace;
font-size: 125%;
background: #eee;
}
</style>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Adding a Unit Test to Your Service</title>
</head>
<body>
<h1>Adding a Unit Test to Your Service</h1>
<p>
This document summarises steps needed in order to add unit test cases to your Perl based SADI service. </p>
<p>
<em><strong>SADI</strong></em> <em><strong>Se</strong></em>rvice <em><strong>S</strong></em>upport) will automatically insert any test cases that you define into your service signature for others to see!</p>
<p>At the end of this tutorial, you will have defined a test case for your service.</p>
<p>Test cases define the expected behaviour of your service based on a specified input. In SADI, you can check the expected behaviour by:</p>
<ol>
<ol>
<ol>
<li>providing the expected output that your specified input generates, or</li>
<li>providing an XPATH expression that can be applied to the service output that was generated from your specified input, or</li>
<li>providing a regular expression that can be applied to the service output that was generated from your specified input.</li>
</ol>
</ol>
</ol>
<p>Test cases that you create can either state all of the above items or any one of them.</p>
<p>This tutorial will generate a test case for the SADI service <a href="./sync_service.html" target="_blank">getGOTerm</a>, that we created in a previous <a href="./sync_service.html" target="_blank">tutorial</a>.</p>
<p>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.</p>
<h2>Table of Contents</h2>
<p>
<a href="#step_1">Step 1: What is needed</a>
<br/>
<a href="#step_2">Step 2: Service unit test generation</a>
<br/>
<a href="#step_3">Step 3: Specifying service input</a>
<br/>
<a href="#step_4">Step 4: Obtaining service output</a><br/>
<a href="#step_5">Step 5: Updating your service registration</a>
<br/>
</p>
<h3><a name="step_1"/>Step 1: What is needed</h3>
<p>
To create unit tests for SADI services using SADISeS, you need to have the following installed on your machine:
</p>
<ol>
<ol>
<ol>
<li>
<strong>Perl</strong>
- perl has to be installed on your machine
</li>
<li>
<strong>A web server</strong>
- this document assumes that you are using Apache2
</li>
<li>
<strong>Perl SADI</strong>
(version <em><strong>0.99.5</strong></em> or greater) - available on <a href="http://search.cpan.org/dist/SADI/" target="_blank">cpan</a></li>
</ol>
</ol>
</ol>
<p>
To implement this a test case for getGOTerm SADI service, you will need, in addition to the above requirements,
</p>
<ol>
<ol>
<ol>
<li>to have followed the tutorial that creates the sadi service <a href="./sync_service.html" target="_blank">getGOTerm</a>.</li>
</ol>
</ol>
</ol>
<p>
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.
</p>
<h3><a name="step_2"/>Step 2: Service unit test generation</h3>
<p>
Before we can specify a unit test, we need to tell SADISeS to generate a file that we can fill in with our information.
</p>
<p>
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 <a href="./sync_service.html" target="_blank">here</a>!</p>
<p>
To generate a unit test file for your service, issue the following command at the command prompt:
</p>
<pre>$ sadi-generate-services.pl -T getGOTerm</pre>
<p>
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.
</p>
<p>
If you open the generated unit test file, you will see something like the following:
</p>
<pre># 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</pre>
<p>
SADISeS has done a nice job in preparing this file for us! </p>
<p>
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.</p>
<p>
We will be using the default file paths that SADISeS created for us in our unit test file.</p>
<h3><a name="step_3"/>Step 3: Specifying service input</h3>
<p>
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!</p>
<p>Create a file<em><strong> ~/Perl-SADI/xml/getGOTerm.xml</strong></em> and put the following XML document in it:</p>
<pre><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></pre>
<p>Once you have placed the text in the file, save it and proceed to the next step!</p>
<h3><a name="step_4"/>Step 4: Specifying service output</h3>
<p>
Now that we have specified the service input for our test case, we need to specify any or all of the following:</p>
<ul>
<ul>
<ul>
<li>expected output,</li>
<li>an xpath expression to apply to the output of our service when given the specified input,</li>
<li>a regular expression to apply to the output of our service when given the specified input.</li>
</ul>
</ul>
</ul>
<p>In this tutorial, we will be only specifying the expected output for our service.</p>
<p>The easiest way to obtain the expected output for our service is to run the service with our sample input and capture the output.</p>
<pre>$ sadi-testing-service.pl Service::getGOTerm ~/Perl-SADI/xml/getGOTerm.xml</pre>
<p>
The output from the service:
</p>
<pre><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></pre>
<p>Create a file<em><strong> ~/Perl-SADI/xml/getGOTerm-output.xml</strong></em> and put the above XML text in it.</p>
<p>Once you have saved the above file, you have successfully specified the expected output for your service.</p>
<h3><a name="step_5" id="step_5"/>Step 5: Updating your service registration</h3>
<p>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. </p>
<p>Finally, the next thing to do is to ensure that we update our service registration on <a href="http://sadiframework.org/registry/">http://sadiframework.org/registry/</a>. </p>
<p>
That's all there is to constructing unit test for your Perl SADI services!</p>
</body>
</html>