Repository navigation
Clients
Instead of calling the API yourself, use a client library in your automated tests. The clients have the same features and version numbers:
- sign-in with a user name and password, or with a token of your identity provider (SSO robot accounts); the token is renewed when it expires,
- the project by name or id,
- insert, get, find (paging, sort, count), reserve and release, update, delete, the data history and the history search,
-
rules written in code, e.g.
Rule.property("$.account.status").eq("active"); the rules of the API request tab of the rich filter (see Filtering) can be passed as they are, - parallel tests never reserve the same row.
The clients 2.0.0 use API version 2: Databucket 3.13.0 or newer (the history search and the history for ROBOT accounts need 3.14.0).
| Language | Package | Requirements | Repository |
|---|---|---|---|
| Java | Maven Central pl.databucket:databucket-client
|
Java 11+ | databucket-java-client |
| Python | PyPI databucket-client
|
Python 3.10+ | databucket-python-client |
| JavaScript / TypeScript | npm databucket-client
|
Node.js 20.19+ | databucket-js-client |
The README of each repository describes the whole API of the client, with examples for test frameworks (e.g. a pytest fixture).
Runnable examples: databucket-examples - small projects with tests that reserve, change, create and find data on the DEMO dataset: reserving a user for a test and releasing it afterwards (also when the test fails), parallel tests, recording changes and checking the history, environment configuration. Java (JUnit 5) now; Python and JavaScript follow.
<dependency>
<groupId>pl.databucket</groupId>
<artifactId>databucket-client</artifactId>
<version>2.0.0</version>
</dependency>Databucket databucket = Databucket.builder("https://databucket.example.com")
.password("tests-robot", System.getenv("DATABUCKET_PASSWORD"))
.project("Acme Shop")
.build();
Bucket<Map<String, Object>> users = databucket.bucket("dev-users");
// reserve one free active user for this test
DataRow<Map<String, Object>> user = users.reserve(Rules.where(
Rule.property("$.account.status").eq("active"),
Rule.property("$.address.country").in("GB", "PL")))
.one()
.orElseThrow();
// ... the test ...
users.release(user.getId());pip install databucket-clientimport os
from databucket import Databucket, Rule, Rules
databucket = Databucket(
"https://databucket.example.com",
username="tests-robot",
password=os.environ["DATABUCKET_PASSWORD"],
project="Acme Shop",
)
users = databucket.bucket("dev-users")
# reserve one free active user for this test
user = users.reserve(
Rules.where(
Rule.property("$.account.status").eq("active"),
Rule.property("$.address.country").in_("GB", "PL"),
)
).one()
assert user, "No free active user"
# ... the test ...
users.release(user.id)npm install --save-dev databucket-clientimport { Databucket, Rule, Rules } from 'databucket-client';
const databucket = new Databucket({
url: 'https://databucket.example.com',
username: 'tests-robot',
password: process.env.DATABUCKET_PASSWORD,
project: 'Acme Shop',
});
const users = databucket.bucket('dev-users');
// reserve one free active user for this test
const user = await users
.reserve(Rules.where(
Rule.property('$.account.status').eq('active'),
Rule.property('$.address.country').in('GB', 'PL')))
.one();
if (!user) throw new Error('No free active user');
// ... the test ...
await users.release(user.id);Create a dedicated user for the tests, e.g. with the ROBOT role (see Roles & permissions), and keep its password or client secret in the secrets of your CI, not in the code. AI agents use the MCP server instead of a client.
Wiki
Work in the project
- Navigation
- Overview
- Searching
- Filtering
- Create/modify/remove data
- Data reservation
- Data details
- Data history
- Tasks execution
- Data export
- Data import
Project settings
Management
API