{panel:title=TOC|titleBGColor=#F7D6C1|bgColor=#FFFFFF}
{toc:style=disc|indent=20px}
{panel}
For those reports supported by QuickBuild, you can retrieve the report data via RESTful APIs. The supported reports included:
||Report Category||Base URI||
|Build Stats|_/rest/buildstats_|
|SCM Changes|_/rest/changes_|
|CheckStyle|_/rest/checkstyle_|
|Cobertura|_/rest/cobertura_|
|JaCoCo|_/rest/jacoco_|
|CPD|_/rest/cpd_|
|EMMA|_/rest/emma_|
|FindBugs|_/rest/findbugs_|
|Fxcop|_/rest/fxcop_|
|JUnit|_/rest/junit_|
|MBUnit|_/rest/mbunit_|
|MSTest|_/rest/mstest_|
|NCover|_/rest/ncover_|
|NUnit|_/rest/nunit_|
|PMD|_/rest/pmd_|
|TestNG|_/rest/testng_|
|Boost Test|_/rest/boost_|
*NOTE*
All report related RESTful APIs use http GET method.
h3. List all supported APIs
||URI||Response Format||Params||
|$baseURI/help|_application/html_| |
for example, all available RESTful functions for JUnit can be accessed by visiting the following URL:
{code}
http://quickbuild:8810/rest/junit/help
{code}
h3. Get the version of category
||URI||Response Format||Params||
|$baseURI/version|_text/plain_| |
For example, you can get the current data version of the JUnit category.
{code}
http://quickbuild:8810/rest/junit/version
{code}
and it will return the data version _2.1_(example only) in text/plain format.
h3. List reports stored in the category
||URI||Response Format||Params||
|$baseURI/reports|_text/xml_| |
For example, visit below URL to list all reports in JUnit category:
{code}
http://quickbuild:8810/rest/junit/reports
{code}
and the response looks like:
{code}
<list>
<string>unprocessed</string>
<string>tests</string>
<string>testsuites</string>
<string>packages</string>
<string>stats</string>
<string>agg_overview</string>
<string>agg_stats</string>
<string>tests_trends</string>
</list>
{code}
h3. Get the report definition (meta data)
||URI||Response Format||Params||
|$baseURI/meta/\{report_name}|_text/xml_|* *report_name*:
Specify the report name you want.|
for example, when visit:
{code}
http://quickbuild:8810/rest/junit/meta/stats
{code}
the response looks like:
{code}
<meta name="stats" group="STATISTICS">
<column name="ID" isKey="false" indexed="false" nullable="false" updatable="false" sqlType="BIGINT" dataType="ID"/>
<column name="buildId" isKey="true" indexed="false" nullable="true" updatable="true" sqlType="BIGINT" dataType="ID"/>
<column name="duration" isKey="false" indexed="false" nullable="true" updatable="true" sqlType="BIGINT" dataType="DURATION"/>
<column name="tests" isKey="false" indexed="false" nullable="true" updatable="true" sqlType="INT" dataType="INTEGER"/>
... ...
</meta>
{code}
You may consider the report meta data as the schema of a table in database.
Each report has an attribute *group* and in QuickBuild, the following groups are used:
* BUILD
* STATISTICS
* HISTORY
* AGGREGATION
the group attribute tells QuickBuild where to find the report, for example, if a report belongs to BUILD group, then this report is stored in build related directory, otherwise, the report is stored in configuration related directory.
h3. List all report sets / aggregations
In QuickBuild, the report data are stored by report sets or by aggregations. The report set is specified in the publish step, and the aggregation name is specified in the aggregation definition.
||URI||Response Format||Params||
|/rest/junit/reportsets/\{report_group}/\{configuration_or_build_id}|_text/xml_| * *report_group*:
The report group, can be one of the following: BUILD, STATISTICS, HISTORY, AGGREGATION
* *configuration_or_build_id:*
for BUILD group, the id should be a valid build id, otherwise, the configuration id should be specified. |
for example, when visit below URL:
{code}
http://quickbuild:8810/rest/junit/reportsets/BUILD/103
{code}
the response looks like:
{code}
<list>
<string>DEFAULT</string>
<string>On Linux</string>
<string>On Windows</string>
</list>
{code}
h3. Get the build stats
||URI||Response Format||Params||
|/rest/junit/buildstats/\{build_id}/\{reportset}|_text/xml_| * *build_id*:
Specify the build id.
* *reportset*:
the report set you want|
for example, when visit:
{code}
http://quickbuild:8810/rest/buildstats/103/DEFAULT
{code}
the response looks like:
{code}
<report name="stats" version="0.0.0" locale="en_US">
<row ID="1" buildId="103" duration="261466" tests="1006" errors="5" failures="7" skips="0" added="994" newFailed="12" notFixed="0" fixed="0" successes="994" success_rate="0.9880715705765407"/>
</report>
{code}
h3. Get the report records
QuickBuild supply two functions to retrieve the detailed report records:
* */size*: get number of total records
* */records*: retrieve the report records by page
||URI||Response Format||Params||
|/rest/junit/size/\{report_name}/\{configuration_or_build_id}/\{reportset}|_text/plain_|* *report_name*
Specify the report name
* *configuration_or_build_id*
According to the report you specified, supply a valid build id when report belongs to BUILD group, otherwise, configuration id is needed.
* *reportset*
Specify the report set or aggregation name
* *filters* - QUERY_PARAM
Specify filters based on SQL to filter the records, for example, duration>5 and duration<10, the fields available can be found in the report meta data definition.|
|/rest/junit/records/\{report_name}/\{configuration_or_build_id}/\{reportset}|_text/xml_|* *report name*
Specify the report name.
* *configuration_or_build_id*
According to the report you specified, the id is a build id when report belongs to BUILD group, otherwise, configuration id is needed.
* *reportset*
The report set or aggregation name
* *offset* - QUERY_PARAM
The first record you want to retrieve. By default, the offset is 0, i.e., from the first record.
* *limit* - QUERY_PARAM
The number of records you want to retrieve. By default, the number of limit is 50.
* *filters* - QUERY_PARAM
Specify filters based on SQL to filter the records, for example, duration>5 and duration<10, the fields available can be found in the report meta data definition.|
for example, first we get a total tests in our JUnit for build 103 by visiting below URL:
{code}
http://quickbuild:8810/rest/junit/size/tests/103/DEFAULT
{code}
and _1005_ is returned, that is, there are 1005 records total, and then we retrive the records from 100 to 119 by visiting below URL:
{code}
http://quickbuild:8810/rest/junit/records/tests/103/DEFAULT?offset=100&limit=20
{code}
the response looks like:
{code}
<report name="tests" version="0.0" locale="en_US">
<row ID="100" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testPojoRetreival" status="PASS" duration="40" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="ADDED"/>
<row ID="101" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jRetreival" status="PASS" duration="58" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="FIXED"/>
<row ID="102" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jSave" status="PASS" duration="34" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="FIXED"/>
<row ID="103" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jHQL" status="PASS" duration="30" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="ADDED"/>
... ...
</report>
{code}
If you want to use some filters to filter the records, for example, to retrieve all failed tests, you may:
{code}
http://quickbuild:8810/rest/junit/size/tests/103/DEFAULT?filters=(status='ERROR') or (status='FAILURE')
{code}
here, we use filter: _status='ERROR' or status='FAILURE'_, the response is _12_, that is, we have 12 failed tests total, and you can retrieve the records now by visiting:
{code}
http://quickbuild:8810/rest/junit/records/tests/103/DEFAULT?filters=(status='ERROR') or (status='FAILURE')
{code}
{toc:style=disc|indent=20px}
{panel}
For those reports supported by QuickBuild, you can retrieve the report data via RESTful APIs. The supported reports included:
||Report Category||Base URI||
|Build Stats|_/rest/buildstats_|
|SCM Changes|_/rest/changes_|
|CheckStyle|_/rest/checkstyle_|
|Cobertura|_/rest/cobertura_|
|JaCoCo|_/rest/jacoco_|
|CPD|_/rest/cpd_|
|EMMA|_/rest/emma_|
|FindBugs|_/rest/findbugs_|
|Fxcop|_/rest/fxcop_|
|JUnit|_/rest/junit_|
|MBUnit|_/rest/mbunit_|
|MSTest|_/rest/mstest_|
|NCover|_/rest/ncover_|
|NUnit|_/rest/nunit_|
|PMD|_/rest/pmd_|
|TestNG|_/rest/testng_|
|Boost Test|_/rest/boost_|
*NOTE*
All report related RESTful APIs use http GET method.
h3. List all supported APIs
||URI||Response Format||Params||
|$baseURI/help|_application/html_| |
for example, all available RESTful functions for JUnit can be accessed by visiting the following URL:
{code}
http://quickbuild:8810/rest/junit/help
{code}
h3. Get the version of category
||URI||Response Format||Params||
|$baseURI/version|_text/plain_| |
For example, you can get the current data version of the JUnit category.
{code}
http://quickbuild:8810/rest/junit/version
{code}
and it will return the data version _2.1_(example only) in text/plain format.
h3. List reports stored in the category
||URI||Response Format||Params||
|$baseURI/reports|_text/xml_| |
For example, visit below URL to list all reports in JUnit category:
{code}
http://quickbuild:8810/rest/junit/reports
{code}
and the response looks like:
{code}
<list>
<string>unprocessed</string>
<string>tests</string>
<string>testsuites</string>
<string>packages</string>
<string>stats</string>
<string>agg_overview</string>
<string>agg_stats</string>
<string>tests_trends</string>
</list>
{code}
h3. Get the report definition (meta data)
||URI||Response Format||Params||
|$baseURI/meta/\{report_name}|_text/xml_|* *report_name*:
Specify the report name you want.|
for example, when visit:
{code}
http://quickbuild:8810/rest/junit/meta/stats
{code}
the response looks like:
{code}
<meta name="stats" group="STATISTICS">
<column name="ID" isKey="false" indexed="false" nullable="false" updatable="false" sqlType="BIGINT" dataType="ID"/>
<column name="buildId" isKey="true" indexed="false" nullable="true" updatable="true" sqlType="BIGINT" dataType="ID"/>
<column name="duration" isKey="false" indexed="false" nullable="true" updatable="true" sqlType="BIGINT" dataType="DURATION"/>
<column name="tests" isKey="false" indexed="false" nullable="true" updatable="true" sqlType="INT" dataType="INTEGER"/>
... ...
</meta>
{code}
You may consider the report meta data as the schema of a table in database.
Each report has an attribute *group* and in QuickBuild, the following groups are used:
* BUILD
* STATISTICS
* HISTORY
* AGGREGATION
the group attribute tells QuickBuild where to find the report, for example, if a report belongs to BUILD group, then this report is stored in build related directory, otherwise, the report is stored in configuration related directory.
h3. List all report sets / aggregations
In QuickBuild, the report data are stored by report sets or by aggregations. The report set is specified in the publish step, and the aggregation name is specified in the aggregation definition.
||URI||Response Format||Params||
|/rest/junit/reportsets/\{report_group}/\{configuration_or_build_id}|_text/xml_| * *report_group*:
The report group, can be one of the following: BUILD, STATISTICS, HISTORY, AGGREGATION
* *configuration_or_build_id:*
for BUILD group, the id should be a valid build id, otherwise, the configuration id should be specified. |
for example, when visit below URL:
{code}
http://quickbuild:8810/rest/junit/reportsets/BUILD/103
{code}
the response looks like:
{code}
<list>
<string>DEFAULT</string>
<string>On Linux</string>
<string>On Windows</string>
</list>
{code}
h3. Get the build stats
||URI||Response Format||Params||
|/rest/junit/buildstats/\{build_id}/\{reportset}|_text/xml_| * *build_id*:
Specify the build id.
* *reportset*:
the report set you want|
for example, when visit:
{code}
http://quickbuild:8810/rest/buildstats/103/DEFAULT
{code}
the response looks like:
{code}
<report name="stats" version="0.0.0" locale="en_US">
<row ID="1" buildId="103" duration="261466" tests="1006" errors="5" failures="7" skips="0" added="994" newFailed="12" notFixed="0" fixed="0" successes="994" success_rate="0.9880715705765407"/>
</report>
{code}
h3. Get the report records
QuickBuild supply two functions to retrieve the detailed report records:
* */size*: get number of total records
* */records*: retrieve the report records by page
||URI||Response Format||Params||
|/rest/junit/size/\{report_name}/\{configuration_or_build_id}/\{reportset}|_text/plain_|* *report_name*
Specify the report name
* *configuration_or_build_id*
According to the report you specified, supply a valid build id when report belongs to BUILD group, otherwise, configuration id is needed.
* *reportset*
Specify the report set or aggregation name
* *filters* - QUERY_PARAM
Specify filters based on SQL to filter the records, for example, duration>5 and duration<10, the fields available can be found in the report meta data definition.|
|/rest/junit/records/\{report_name}/\{configuration_or_build_id}/\{reportset}|_text/xml_|* *report name*
Specify the report name.
* *configuration_or_build_id*
According to the report you specified, the id is a build id when report belongs to BUILD group, otherwise, configuration id is needed.
* *reportset*
The report set or aggregation name
* *offset* - QUERY_PARAM
The first record you want to retrieve. By default, the offset is 0, i.e., from the first record.
* *limit* - QUERY_PARAM
The number of records you want to retrieve. By default, the number of limit is 50.
* *filters* - QUERY_PARAM
Specify filters based on SQL to filter the records, for example, duration>5 and duration<10, the fields available can be found in the report meta data definition.|
for example, first we get a total tests in our JUnit for build 103 by visiting below URL:
{code}
http://quickbuild:8810/rest/junit/size/tests/103/DEFAULT
{code}
and _1005_ is returned, that is, there are 1005 records total, and then we retrive the records from 100 to 119 by visiting below URL:
{code}
http://quickbuild:8810/rest/junit/records/tests/103/DEFAULT?offset=100&limit=20
{code}
the response looks like:
{code}
<report name="tests" version="0.0" locale="en_US">
<row ID="100" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testPojoRetreival" status="PASS" duration="40" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="ADDED"/>
<row ID="101" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jRetreival" status="PASS" duration="58" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="FIXED"/>
<row ID="102" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jSave" status="PASS" duration="34" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="FIXED"/>
<row ID="103" packageName="org.hibernate.test.entitymode.multi" className="MultiRepresentationTest" testName="testDom4jHQL" status="PASS" duration="30" hasSysout="true" totalRuns="2" failedRuns="0" passedRuns="2" diffStatus="ADDED"/>
... ...
</report>
{code}
If you want to use some filters to filter the records, for example, to retrieve all failed tests, you may:
{code}
http://quickbuild:8810/rest/junit/size/tests/103/DEFAULT?filters=(status='ERROR') or (status='FAILURE')
{code}
here, we use filter: _status='ERROR' or status='FAILURE'_, the response is _12_, that is, we have 12 failed tests total, and you can retrieve the records now by visiting:
{code}
http://quickbuild:8810/rest/junit/records/tests/103/DEFAULT?filters=(status='ERROR') or (status='FAILURE')
{code}