Getting Started¶

Requirements¶

To get started using Ibutsu, you’ll need to set up a server, and then start sending results to it.

Using the pytest plugin¶

Sending results on-the-fly¶

Ibutsu has a companion pytest plugin which can be used to send results to Ibutsu from pytest.

You can install the pytest plugin via pip:

pip install pytest-ibutsu

Once installed, you can activate the Ibutsu pytest plugin by specifying your Ibutsu server on the command line:

pytest --ibutsu http://ibutsu-server/api

If you’re running Ibutsu locally for development, and you want to upload results to your local instance, you can do that too:

pytest --ibutsu http://127.0.0.1:8080/api

You can also specify the project, source and extra metadata via command line arguments:

pytest --ibutsu http://ibutsu-server/api --ibutsu-project my-project
pytest --ibutsu http://ibutsu-server/api --ibutsu-data key=value --ibutsu-data key2=value2
pytest --ibutsu http://ibutsu-server/api --ibutsu-source my-test-run-2

Importing results from the archive¶

Ibutsu’s pytest plugin will create a .tar.gz archive that can be used to upload results in the event that connection to the Ibutsu server is not possible.

Via the Ibutsu UI¶

Simply click on the “Import” button in the top right of the Ibutsu UI and select the appropriate archive.

Via the Ibutsu API¶

Archives may be imported via the import API endpoint. For example, one may use the following curl command:

curl --form importFile=@<file-name>.tar.gz http://ibutsu-server/api/import

Importing results from JUnit XML¶

JUnit XML is supported from pytest, Jenkins, Maven/Surefire, Gradle, and other runners that emit standard JUnit-style reports.

Via the Ibutsu UI¶

If you have legacy pytest test results stored in JUnit XML files, those can be imported via the Ibutsu UI. Simply click on the “Import” button in the top right, and select your XML file.

A run will be created for each testsuite in the XML file. For each testcase of the testsuite, a result will be created.

Note: for new test results, it is strongly recommended to use the pytest plugin. The XML import does not upload screenshots and log files.

Via the Ibutsu API¶

For programmatic imports, prefer the official API clients:

Python: ibutsu-client-python
TypeScript/JavaScript: ibutsu-client-javascript

Those repositories include usage examples and recommended integration patterns.

You can also call the import API endpoint directly with curl:

curl --request POST \
  --header "Authorization: Bearer <token>" \
  --form importFile=@<file-name>.xml \
  --form project=my-project \
  --form source=ci-pipeline-42 \
  --form 'metadata={"env":"perf","build":"166"}' \
  https://<ibutsu-host>/api/import

The server responds when the file is accepted for background import; poll GET /import/{id} or refresh the Runs view to see the new data.

Installing the Python API client¶

If you are using Python, install the API client via pip:

pip install ibutsu-client