CDash:API

From KitwarePublic
Jump to navigationJump to search

Starting in 1.2, CDash is introducing the CDash API with a minimal function. The API is still in beta and the response code might change in the near future. In CDash 1.7 we are adding a more complex API framework.

General API

This section describes the CDash web API. The CDash REST API is generic and the GET url is usually formatted as follows:

 http://mycdashserver/api/?method=method_name&task=task_name&project=project_name

The URL should be encoded accordingly to the HTTP 1.1 protocol and by default the result is returned as a JSON array.

Project API

  • Method name: project

List

  • Task name: list
  • Description: Returns a list of projects id and names
 http://mycdashserver/api/?method=project&task=list
 
  • Return an array of projects:
    • array[]['id'] = project id
    • array[]['name'] = project name


Build API

  • Method name: build

Defects

  • Task name: defects
  • Project name: mandatory
  • Description: Returns an array of build defects over time (currently limited to the 1000 last entries)
 http://mycdashserver/api/?method=build&task=defects&project=MyProject
 
  • Return an array of builds: array(build);
    • build['month'] = month of the build
    • build['day'] = day of the build
    • build['year'] = year of the build
    • build['time'] = time of the build
    • build['builderrors'] = number of build errors
    • build['buildwarnings'] = number of build warnings
    • build['testnotrun'] = number of tests not run
    • build['testfailed'] = number of tests failed

Checkins/Defects

  • Task name: checkinsdefects
  • Project name: mandatory
  • Description: Returns an array of build defects and number of updated files for the build
  • Currently limited to the last 1000 builds for the project
 http://mycdashserver/api/?method=build&task=checkinsdefects&project=MyProject
 
  • Return an array of builds: array(build);
    • build['nfiles'] = number of updated files
    • build['builderrors'] = number of build errors
    • build['buildwarnings'] = number of build warnings
    • build['testnotrun'] = number of tests not run
    • build['testfailed'] = number of tests failed

Site/Test Failures

  • Task name: sitetestfailures
  • Project name: mandatory
  • Group: optional: Nightly, Continuous, Experimental
  • Description: returns an array of sites and corresponding names of the failing tests.
 http://mycdashserver/api/?method=build&task=sitetestfailures&project=MyProject&group=Nightly
 
  • Return an array of sites with the index being the id of the build
    • site['name'] = name of the machine
    • site['buildname'] = name of the build
    • site['cpu'] = processor speed
    • site['memory'] = physical memory
    • site['tests'] = name of the tests

Schedule a build (build management)

  • Task name: schedule
  • project (mandatory) - Name of the project
  • repository (mandatory) - Name of the repository
  • userid (optional) - User scheduling the build (default is administrator)
  • type (option) - Experimental, nighty, continuous (Experimental=0,Nightly=1,Continuous=2)
  • module (optional) - Name of the repository module
  • tag (optional) - Name of the repository tag
  • suffix (optional) - Suffix for the build
  • configuration (optional) - Configuration type for compilation (Debug=0,Release=1,RelWithDebInfo=2,MinSizeRel=3)
  • cmakeversion (optional) - Version of CMake to use
  • siteid (optional) - Specify that the build should run on this site
  • osname (optional) - Name of the OS to run the build
  • osversion (optional) - Version of the OS to run the build
  • osbits (optional) - Number of bits of the target OS
  • compilername (optional) - Target compiler
  • compilerversion (optional) - Target compiler version
  • libraryname (optional) - Library name (currently only one can be specified)
  • libraryversion (optional) - Library version
  • If none of the optional parameters are not set, CDash will try to schedule the build on any available machines.
  • Description: returns an array with the current status of the schedule.
 http://mycdashserver/api/?method=build&task=schedule&project=MyProject
 
  • Return an array containing the status of the scheduling
    • status['scheduled'] = returns 1 if the build has been scheduled
    • status['statusid'] = internal status id for further reference

Coverage API

  • Method name: coverage

Coverage per directory

  • Task name: directory
  • Project name: mandatory
  • Description: Return the number of lines untested per directory
 http://mycdashserver/api/?method=coverage&task=directory&project=MyProject
  • Returns an array of LOC tested and untested
    • array[directory_fullpath]['loctested'] = # loc tested
    • array[directory_fullpath]['locuntested'] = # loc untested

User API

  • Method name: user

Defects per user

  • Task name: defects
  • Project name: mandatory
  • Description: Return the commit statistics per user
 http://mycdashserver/api/?method=user&task=defects&project=MyProject
  • Returns an array of users
    • array[username]['builderrors'] = number of errors and warning caused by the user
    • array[username]['builderrorsfiles'] = number of commits causing either a fix or failure of errors and warnings
    • array[username]['buildfixes'] = number of fixes (warnings or errors) done by the user
    • array[username]['buildfixesfiles'] = number of commits causing either a fix or failure of errors and warnings
    • array[username]['testerrors'] = number of test failing caused by the user
    • array[username]['testerrorsfiles'] = number of files committed that produced a test failure
    • array[username]['testfixes'] = number of test fixed by the user
    • array[username]['testfixesfiles'] = number of files committed that fixed a test
    • array[username]['neutralfiles'] = number of commits that didn't fix or break the dashboard

Get build id (old API)

  • URL:
 /api/getbuildid.php?
  • Parameters:
    • project: name of the project
    • site: name of the site
    • siteid: override the site name if siteid is provided (optional)
    • stamp: time stamp of the build
    • name: build name
  • Returns:
    • <buildid>buildid</buildid>
    • <buildid>not found</buildid> if no buildid found
  • Example:
 /api/getbuildid.php?project=VTK&site=singaporecrisp&stamp=20081013-0109-Experimental&name=Linux-c%2B%2B

Get user id (Old API)

  • URL:
 /api/getuserid.php?
  • Parameters:
    • project: name of the project
    • author: name of the cvsuser/svnuser
  • Returns:
    • <userid>userid</userid>
    • <userid>not found</userid> if no user found
  • Example:
 /api/getuserid.php?project=VTK&cvsuser=test