Skip to content

Clients

Krzysztof Słysz edited this page Nov 16, 2026 · 4 revisions

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.

Java

<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());

Python

pip install databucket-client
import 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)

JavaScript / TypeScript

npm install --save-dev databucket-client
import { 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);

The user of the tests

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.

Clone this wiki locally