Testopia:Documentation:XMLRPC

Back to the Testopia Main Page

What's New!

2007-05-18	TestCase: Added get_bugs method TestCaseRun: Added get_bugs method Product: Added get_milestones method
2007-03-07	TestCaseRun: Added a new_values attribute, called update_bugs, to the update method TestCase: The update method will not allow changes to a TestCase's author_id
2007-01-09	TestCase: Added add_tag method TestCase: Added remove_tag method TestCase: Added get_tags method TestPlan: Added add_tag method TestPlan: Added remove_tag method TestPlan: Added get_tags method TestRun: Added add_tag method TestRun: Added remove_tag method TestRun: Added get_tags method
2007-01-05	Documentation Only: Corrected the data type of the query parameter for all list methods to hashmap TestCase: Modified create method to require a plan id number (plan_id) TestCase: Added link_plan method TestCase: Added unlink_plan method TestPlan: Added get_components method
2006-12-14	The TestCaseRun.update method now requires environment_id as a parameter
2006-12-12	Welcome to Version 1.1 More consistent, more secure, more efficient, and faster! API returns native ID numbers for all objects and attributes Results are consistent across an object's methods calls Object attributes match query parameters Lookup functions available for converting from ID numbers to string names Objects updated: TestPlan, TestCase, TestRun, and TestCaseRun Consult the specific object documentation in this WIKI for more details Added get_test_plan method to TestRun object Added an Environment object
2006-12-08	TestCase: Added setup and breadown to get/setText methods TestCase: Added component add/remove/list methods Component: New object! Build: Added get, create, and updated methods TestCaseRun: Notes are now appended during an update method call TestPlan: Added get_builds method TestRun: Added get_test_cases and get_test_case_runs methods
2006-11-27	Added instructions for using Basic Authorization with an Apache server New query examples that do not use binary charts New API objects: Build, Product, and User New methods for TestPlan object New parameters added for managing query result sizes. pagesize is used to set the number of records returned. The default is 24. page is used to return a page of results based on pagesize. The default value for page is zero. For example, setting page equal to zero will return the first 24 records. Setting page equal to 1 will return the second set of 24 records. The new parameters are added to any "list" method: $proxy->call('TestPlan.list', {pagesize=>10, page=>0});
2006-10-18	Added Instructions for using SSL and Perl (SOAP::Lite) on SLED10
2006-10-04	Added an example of an error response
2006-09-21	Added code for SSL (https) access to the Java client (not necessary for Perl client)
2006-09-20	Added code for Basic Authorization to the sample clients

Project Description

Provide a means for the programmatic creation, modification, and reporting of inherent Bugzilla Testopia objects, such as test plans, test cases, and test runs. Scope will later expand to cover actual bugs and products.

The API is accessed through XML Remote Procedure Calls (XML-RPC). Bascially, a client creates an XML document and sends it to the Bugzilla server via an HTTP post.

An example of an XML request:

<?xml version="1.0" encoding="UTF-8"?>
   <methodCall>
      <methodName>TestPlan.get</methodName>
      <params>
         <param>
            <value>
               <int>1</int>
            </value>
         </param>
      </params>
   </methodCall> 

An example of an XML response:

<?xml version="1.0" encoding="UTF-8"?>
   <methodResponse>
      <params>
         <param>
            <value>
               <struct>
                  <member>
                     <name>author</name>
                     <value>
                        <string>user@company.com</string>
                     </value>
                  </member>
                  <member>
                     <name>editor</name>
                     <value>
                        <string>user@company.com</string>
                     </value>
                  </member>
                  <member>
                     <name>name</name>
                     <value>
                        <string>A Test Plan</string>
                     </value>
                  </member>
                  <member>
                     <name>default_product_version</name>
                     <value>
                        <string>other</string>
                     </value>
                  </member>
                  <member>
                     <name>plan_id</name>
                     <value>
                        <int>1</int>
                     </value>
                  </member>
                  <member>
                     <name>product</name>
                     <value>
                        <string>TestProduct</string>
                     </value>
                  </member>
                  <member>
                     <name>creation_date</name>
                     <value>
                        <string>2006-08-03 13:20:53</string>
                     </value>
                  </member>
                  <member>
                     <name>type</name>
                     <value>
                        <string>Unit</string>
                     </value>
                  </member>
                  <member>
                     <name>isactive</name>
                     <value>
                        <int>1</int>
                     </value>
                  </member>
               </struct>
            </value>
         </param>
      </params>
   </methodResponse>

An example of an error response:

<?xml version="1.0" encoding="UTF-8"?>
   <methodResponse>
      <fault>
         <value>
            <struct>
               <member>
                  <name>faultString</name>
                  <value>
                     <string>Too many parameters.</string>
                  </value>
               </member>
               <member>
                  <name>faultCode</name>
                  <value>
                     <int>4</int>
                  </value>
               </member>
            </struct>
         </value>
      </fault>
   </methodResponse>

Getting Started

Requirements

The examples for this project use the following libraries:

Programming Language	Software	Special Notes
Perl	SOAP::Lite	Instructions for using SSL and Perl on SLED10
Java	Apache XML-RPC
PHP	XML-RPC for PHP

You can, of course, code the XML document via strings or the Document Object Model (DOM) and then maually do a HTTP post, but why?

Sample Clients

Perl

use SOAP::Transport::HTTP;  # Need for Basic Authorization subroutine

use XMLRPC::Lite;           # From the SOAP::Lite Module
 
my $proxy = XMLRPC::Lite->proxy("YOUR_URL_TO_BUGZILLA_GOES_HERE"/tr_xmlrpc.cgi);

# Result is a hash map
my $soapresult = $proxy->call('TestPlan.get', 1);

# Error checking
die_on_fault($soapresult);

# Print each key/value pair 
foreach (keys(%$soapresult)) 
{
	print "$_: $$soapresult{$_}\n";
}

# Add the following subroutine to submit a userid/password for basic authorization
sub SOAP::Transport::HTTP::Client::get_basic_credentials 
{ 
	return 'userid' => 'password';
}

sub die_on_fault 
{
	my $soapresult = shift;

	if ($soapresult->fault) 
	{
		die $soapresult->faultcode . ' ' . $soapresult->faultstring;
	}
}

Java

import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;

import java.net.URL;
import java.util.HashMap;
import java.util.ArrayList;

// Needed for SSL
import java.security.cert.X509Certificate;
import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLSession;
import javax.net.ssl.TrustManager;
import javax.net.ssl.X509TrustManager;

public class RPCClient
{
 	// 
 	// Trust All Certificates - Needed for SSL Client
 	// 
	private static void TrustAllCerts()
		throws java.security.NoSuchAlgorithmException,
		       java.security.KeyManagementException  
	{
		// Create a trust manager that does not validate certificate chains

		TrustManager[] trustAllCerts = new TrustManager[] 
	    {
	        new X509TrustManager() 
	        {
	            public X509Certificate[] getAcceptedIssuers() 
	            {
	                return null;
	            }
	 
	            public void checkClientTrusted(X509Certificate[] certs, String authType) 
	            {
	                // Trust always
	            }
	 
	            public void checkServerTrusted(X509Certificate[] certs, String authType) 
	            {
	                // Trust always
	            }
	        }
	    };
	 
	    // Install the all-trusting trust manager
	    SSLContext sc = SSLContext.getInstance("SSL");
	    
	    // Create empty HostnameVerifier
	    HostnameVerifier hv = new HostnameVerifier() 
	    {
	    	public boolean verify(String arg0, SSLSession arg1) 
	    	{
	    		return true;
	        }
	    };

	    sc.init(null, trustAllCerts, new java.security.SecureRandom());
	    HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
	    HttpsURLConnection.setDefaultHostnameVerifier(hv);
	}
 
	public static void main(String[] args)
	{
 		try
		{
		    TrustAllCerts();

		    XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
		    config.setServerURL(new URL("/* YOUR_URL_TO_BUGZILLA_GOES_HERE/tr_xmlrpc.cgi */"));
		    config.setBasicUserName("userid");
		    config.setBasicPassword("password");

		    XmlRpcClient client = new XmlRpcClient();
		    client.setConfig(config);

		    ArrayList<Object> params = new ArrayList<Object>();
		    params.add(1);

		    HashMap result = (HashMap) client.execute("TestPlan.get", params);

		    System.out.println(result);
		}
 		catch (Exception e)
		{
			e.printStackTrace();
		}
	}
}

PHP

include_once("xmlrpc.inc");

$client = new xmlrpc_client("/tr_xmlrpc.cgi", "apibugzillastage.provo.novell.com", 443, "https");
$client->setCredentials($username, $password);
$client->setSSLVerifyPeer(TRUE);
$client->setDebug(0);

$call = new xmlrpcmsg('TestPlan.get', array(new xmlrpcval(1, "int")));

if (!($res = $client->send($call))) {
       print "Could not connect to HTTPS server.";
}

if ($res->faultCode() == 0) {
       $value = $res->value();
}
else {
       print "XML-RPC Fault #" . $res->faultCode();
}

API Documentation

All XML-RPC requests are sent to a single Bugzilla CGI called tr_xmlrpc.cgi. Its location will be based on your specific Bugzilla installation. Normally the CGI will be found at the root URL of Bugzilla, for example, http://bugzilla.company.com/tr_xmlrpc.cgi

Objects

• Build
• Component
• Environment
• Product
• Tag
• User
• TestPlan
• TestCase
• TestRun
• TestCaseRun

FAQ

1. Where can I find more coding examples?
   • Here.
2. Where can I find the query examples again?
   • Here.
3. Where can I find how to setup Apache for use with the API and Basic Authentication?
   • Here.
4. The example above doesn't compile for me because I'm too bleeding edge for my own good, what gives?
   • A newer java sample client

Back to the Testopia Main Page