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

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