Write custom report renderer extension for Q7

Overview

To provide new report format, we need to provide implementation of only one interface and one extension point.

Requirements

Configured Q7 development environment with q7.extensions repository cloned to some local folder.

Please refer to Development Guides for instructions for initial setup.

 Guide requires a skilled Eclipse Developer to proceed.

Implementation steps

1. Create a plug-in project.
2. Add dependencies to 2 plugins:

   • com.xored.watson.core

   • com.xored.q7.reporting
3. Create extension to extension point com.xored.q7.reporting.reportRenderer
4. Write implementation of interface com.xored.q7.reporting.core.IReportRenderer.
5. Build binary version of plugin with update site.
6. Include into Q7 RCP and Q7 Runner.
   1. Install extension plugin into Q7 RCP.
   2. Build customized runner instance using instruction below.

Repository with example code

We setup repository on github: https://github.com/xored/q7.extensions.reporting

Repository contain reference implementation of report renderer. And could be used as initial point for report implementation.
Repository contain 2 folders:

• reporting - contain plugin, feature and update site for described here reporting example.
• runner - contain maven build scenario and product file to build customized q7 runner with include of reporting plugin.

Repository content could be builded using:

Build will provide a update site for sample plugin, it could be installed directly into Q7 RCP.
And a customized q7runner version with sample plugin included.

Details for com.xored.q7.reporting.reportRenderer extension point.

To add new report kind please contribute a com.xored.q7.reporting.report.renderer extension point.
Following code show how new report kind are contributed in com.xored.q7.reporting.example plugin in q7.extensions repository.

For this extension we need to implement com.xored.q7.reporting.core.IReportRenderer interface.

Before we go into sample implementation let's talk about Q7 Reporting format.

So empty implementation will look like:

Some details about report format and used structured will be described below.

Q7 Report format

Then Q7 execute test cases it stores execution information in binary EMF based report format. q7.report files are zip archives with individual report's stored in.

Q7ReportIterator class is used to iterate over individual reports.

Following example could illustrate how to iterate over Q7 report file:

Report model description:

Q7 report are EMF object described by following object hierarchy:

Model	Description
	Report - base object for all Q7 reports. Each report is a tree of nodes. Root node represent report itself. Root Node name is test case name. Each child is some activity inside test case execution. Too level childs of report are execution of contexts, and ecl scenario. Childs of contexts could be another contexts. Childs of scrip cloud be ecl commands. Node- tree node. startTime, endTime - begin and end time of node in milliseconds. children - child nodes events - events captured during this node execution name - node name, for root node name of test case properties - Map<String,EObject>. By default Q7 use Q7Info object stored with "q7" key for detailed information about node. Event- different event object. Like error log entries. time - time in milliseconds then event occur. properties - list of event properties. data - EMF object represent event. Currently used only EclipseStatus to represent error log events. source - stack trace there event occur. kind - event kind. Could be Info, Begin, End. Begin, End nodes for events how execute longer when particular node time. color - could be used to display event.  Snapshot - Represent some state object associated with node. Right now used only for errors to store advanced information about error. time - then snapshot was captured. properties - list of properties. data - EMF object associated with snapshot. Screenshot - png image captured as part of snapshot.
	Q7Info object represent additional information associated with Report Root node and with some other child nodes. id - testcase id for root node, context id, testcase id for top level childs. any identifier for other nodes. type - could be Context, Testcase, Script, EclCommand result - execution status. Could be Pass, Fail, Skip, Warn. message - error or warning message if result is Fail. line - line number where problem is occur. tags - for root node contain list of tags for test case. description - contents of description field of test case. contextKind - context type identifier.

EclipseStatus

Eclipse status object represent error log entry occurred during test case execution.

Model	Description
	children - list of child status entries. code - eclipse error log status code. message - error message. plugin - bundle identifier. severity - OK, INFO, WARNING, ERROR - please refer to IStatus Eclipse class. exception - JavaException EMF object. featureGuess - guessed feature name, if plugin are belong to feature. threadName - thread name, there entry occur.

Advanced information

Contain information about execution error. In tree like format.

Model

Description

AdvancedInformation - root object. threads - list of stack traces for each thread. jobs - list of currently executed jobs. message - some error message. nodes - tree of childs with properties. No particular format used. StackTraceEntry - stack trace id - method name threadName - name of thread threadClass - class name JobEntry - represent Eclipse job. id - identifier name - job name jobClass - job class name state - running, waiting, blocked rule - rule path ruleClass - rule class name InfoNode - tree for some additional information children - child nodes name - node name properties - list of properties NodeProperty - properties used in InfoNode

Running example plugin from Q7 Dev environment

To execute example report from Q7 we could do following:

• Start Q7 from development environment or standalone Q7.
• Create Q7 project.
• Import samples.report from com.xored.q7.reporting.example/samples folder in file system.
• Open report file in Q7 report viewer.
• Use Save As button in report editor.
  
• After Finish button clicked we will see report generated by sample plugin.
   

Delivering report renderer

Best way to deliver new report renderer is to create update site with required plugin.

Our example repository provide maven/tycho version of build environment to provide a update site.
Eclipse PDE build could also be used.

Updatesite could be easy installed into Q7 RCP using standard Eclipse update mechanisms. 

Running example plugin using Q7 Runner.

To use runner with custom report format we need to build version of runner with included update site.

Let's perform following steps to perform this:

1. Clone our example repository.
2. Customize q7.extensions/runner/pom.xml.
   1. Update groupId to be one you like. Default value is "com.xored.q7_my". 
   2. Specify update site with extension plugins to use.
3. Customize q7.extensions/runner/q7runner.product to contain required for extension features. Committed version contain link to example repository.
   
   

4. Build q7 runner

   Build will provide archived version of q7runner in target folder and will install q7runner into local maven repository.

5. Execute q7runner or maven plugin.
   Please refer to Q7 Runner for more information about runner.
   And Q7 Maven Pluginfor more information about using maven plugin.
   1. Using command line.
      Please also specify parameter "-report  sample1;/path/reportfolder/reportName".
      This will tell Q7 runner to use report renderer with id "sample1" and to put report file with reportName into folder /path/reportfolder. 

   2. Using maven plugin.
      Please change q7-maven-plugin version to 1.2.1-SNAPSHOT.
      And when in configuration area of q7-maven-plugin please do following modifications.