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. The same scenarios in Java (JUnit 5), Python (pytest) and JavaScript / TypeScript (Playwright Test).
<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