BRAVA: IPK BrAPI Validator

Test suite for BrAPI servers. Test your server at http://webapps.ipk-gatersleben.de/brapivalidator/.

Please note: This tool is under development and not fully tested. If you find any errors or bugs, please report them as an issue!

BRAVA currently has two execution modes, simple and advanced mode. Simple mode contains the basic functionality: you can test any BrAPI server and get every endpoint defined in /calls tested.

The advanced mode requires a database (it can be an H2 database) to store test results and resource information. It includes a public repository list and the possibility to register resources to be tested periodically.

Running BRAVA

Using the Docker image from Dockerhub

You can run BRAVA by using the ready-to-go Docker image on Dockerhub: https://hub.docker.com/r/ipkbit/brapi-validator

Execute following commands in your linux shell (you need to have Docker installed):

$  docker pull ipkbit/brapi-validator
$  docker run -d --rm -p 8080:8080 ipkbit/brapi-validator

BRAVA will then be available at the following URL: http://localhost:8080

To change the published port to something else than 8080 you have to change the first port value in the -p Parameter.

Example for mapping to port 80 instead of 8080 on the host:

$  docker run -d --rm -p 80:8080 ipkbit/brapi-validator

BRAVA will then be available at the following URL: http://localhost

(For details about the Docker port mapping please refer the Docker documentation: https://docs.docker.com/config/containers/container-networking/#published-ports )

Running BRAVA by compiling the source code on your machine

It is a bit of an awkward process right now. We'll migrate to Gradle and make things smoother in the future.

For now, you need to install Maven on your system.

To start up the simple version for testing of BrAPI endpoints without support for scheduled testing:

1. Create an empty file named config.properties in src/main/resources based on config.properties.example in the same folder.

2. If your network requires use of an HTTP(s) proxy, then set the two proxy properties in your config.properties file:

http.proxyHost=
http.proxyPort=

3. Run it locally for the first time with:

mvn -U clean package jetty:run

This will start jetty on port 8080, accessible at http://localhost:8080/brapivalidator.

Running BRAVA in advanced mode

Running BRAVA in advanced mode provides a public repository list and scheduled testing.

WARNING: This procedure is highly dependent on your environment and it hasn't been tested thoroughly. Something is likely to go wrong. DON'T PANIC and create an issue.

1. In pom.xml search for this line:

<warSourceDirectory>${webappHome}</warSourceDirectory>

and replace it with:

<warSourceDirectory>${webappHome}/advanced</warSourceDirectory>

2. Go to src/main/resources and rename config.properties.example to config.properties. Fill the fields with configuration relevant to your database connection:

## Database username
dbuser=
# Database password
dbpass=
# JDBC connect string to your database
dbpath=
## mysql
# dbpath=jdbc:mysql://localhost/brava

3. Make sure the required JDBC driver is on the classpath by updating the pom.xml file:

Uncomment relevant XML block in pom.xml:

3. Run it locally with:

mvn -U clean package jetty:run

This will start up BRAVA and create the database tables required for BRAVA to operate.

Jetty and Tomcat

To start BRAVA locally use:

mvn jetty:run

To deploy to a local Tomcat instance use:

mvn tomcat7:deploy

The tomcat server location must be defined as maven parameters. For example as a profile in settings.xml:

<profile>
  <id>profileid</id>
  <activation>
    <activeByDefault>true</activeByDefault>
  </activation>
  <properties>
    <appserver.name>production_server</appserver.name>
    <appserver.url>http://website.com:1234/manager/text</appserver.url>
    <appserver.path>/brapivalidator</appserver.path>
  </properties>
</profile>

Also remember to add the server user and encrypted password to settings.xml.

Docs

API

You can send GET requests to the server to test other servers easily, and get a JSON report:

/api/test/call?url={serverURL}&brapiversion={brapiVersion}

For example:

/api/test/call?url=http://brapi.org/server&brapiversion=v1.1

You can also get a report generated by the scheduled report system (either public or private) by using its id:

/api/testreport/{reportID}

Testing

This testing suite uses RestAssured for testing.

To validate the responses, JsonSchema is used. All schemas are located in src/test/resources/schemas.

The test configurations are stored in two ways. For the 'simple' tests, where one resource is tested for status code, content type and response schema, are stored in tests.json.

The complex tests (Test Collections) are stored in the collections/ folder. They roughly follow Postman's collections format. Instead of using JavaScript for the tests, we define them using a few simple commands.

Command	Description	Example
StatusCode:{int}	Check the status code of the response	StatusCode:200
ContentType:{String}	Check the Content Type of the response	ContentType:application/json
Schema:{path}	Check the response against a Schema located in src/main/resources/schemas	Schema:/metadata
GetValue:{jsonpointer}:{variableName}	Stores the value of the response in the pointer location	GetValue:/result/data/0/germplasmDbId:germplasmDbId
IsEqual:{jsonpointer}:{variableName}	Checks the value of the response in the pointer location with a stored variable	IsEqual:/result/germplasmDbId:germplasmDbId
{command}:{value}:breakiffalse	This flag stops the current endpoint testing if the test is failed.	StatusCode:200:breakiffalse

Adding tests

• Edit test collection found in /collections/

Building a Docker Image by your own

You can use the included Dockerfile to build a Docker Image of the BRAVA application that includes a Tomcat server. The Tomcat server will only have the BRAVA application. To use this with your own BRAPI application you can start the Docker Image and use the local test ("Test your own" tab in the BRAVA frontend) to point it to your machine. You can use host.docker.internal in the URL, localhost will resolve to the BRAVA servercontainer and can thus not be used.

To build you can use docker build --build-arg HTTPS_PROXY=<[http|https]://proxyserver:port> --build-arg HTTP_PROXY=<[http|https]://proxyserver:port -t brava . and you can run it using docker run -d --rm -p 8080:8080 brava. You can now access the BRAVA application at http://localhost:8080/ and use for example http://host.docker.internal:5000/brapi/v1 as the url that needs to be tested.