Stash API

Added inv2.0.25

Stash API is currently in beta. It’s suitable for real-world high-volume use, but some of the APIs may change before general availability.

To opt-in into the beta send us an email on support@artillery.io.

Stash API provides a persistent key-value store for use in your Artillery tests, and offers Redis-compatible features like working with key-value pairs, lists, counters, and more.

Features

Full support for most Redis commands
Works in all environments where Artillery runs - local, CI, AWS Fargate, AWS Lambda, Azure ACI
Zero-config — just pass in your Artillery Cloud API key when running a test
Globally-distributed with low latency writes & reads

Use cases

Making sure that data is only used once in a test by different VUs
Sharing data between VUs
Storing large datasets that get reused between tests
Storing arbitrary data generated by VUs for later analysis

Usage

Stash API is available to all users with a subscription to the Business or Enterprise plans. It is not included on free or Team plans.

To use Stash API, run Artillery with --key flag to pass in your Artillery Cloud API key. Artillery will create & configure a Stash API client automatically, which will be available under the global.artillery.stash object. There is no other configuration required to use Stash API.

Stash API is supported by Artillery CLI v2.0.25+. You can check your version of Artillery CLI with:


artillery version

Example

The following code defines a simple Playwright-based load test. The helloWorld function uses the artillery.stash object to write data to the Stash database.

stash-demo.ts


import { Page } from '@playwright/test';
 
export const config = {
  target: 'https://www.artillery.io',
  engines: {
    playwright: {}
  },
  phases: [{
    arrivalCount: 5,
    duration: '10s'
  }]
};
 
export const scenarios = [{
  engine: 'playwright',
  testFunction: helloWorld
}];
 
async function helloWorld(page: Page, userContext: any) {
  // Store a unique key/value from this virtual user. $uuid is a
  // built-in variable with a unique id for each VU
  const keyName = `vuId_${userContext.vars.$uuid}`
  await global.artillery.stash.set(, new Date());
  // Set automatic expiry on the key - delete after 10 minutes
  await global.artillery.stash.expire(keyName, 10 * 60);
 
  await page.goto('https://www.artillery.io/');
  await page.click('text=Docs');
}

To make the Stash API available in the test, we have to run it with a valid Artillery Cloud API key:


artillery run stash-demo.ts --key $ARTILLERY_CLOUD_API_KEY

API

Most Redis commands are supported. The most commonly used ones are listed below.

Get/set/delete keys


// Set values
await artillery.stash.set('key1', 'val1');
await artillery.stash.set('key2', 'val2');
 
// Delete keys/values
await artillery.stash.del('key1', 'key2');

Work with keys


// Check if keys named "key1" and "key2" exist
await artillery.stash.exists('key1', 'key2');
 
// Set expiration time on a key for it to be deleted automatically
// Expire key "key1" after 60 seconds
await artillery.stash.expire('key1', 60)
// Expire key "key1" at a specific time - 24 hours from now
await artillery.stash.expireat('key1', Math.floor(Date.now() / 1000) + 24 * 60 * 60);
 
// Get a list of all key names
// NOTE: This can take a while for databases with a large number of keys - consider using scan() instead
await artillery.stash.keys();
 
// Scan the database for keys matching a glob pattern
// Get first batch of results:
const [cursor, keys] = await artillery.stash.scan(
  0,              // initial value for the cursor
  { match: '*' }, // glob for matching key names
  100,            // return up to 100 results each time
);
// Call scan() again with the return value in "cursor" to get more results
const moreKeys = await artillery.stash.scan(cursor, { match: '*' }, 100);

Lists


// Push values to a list
await artillery.stash.lpush('usernames', 'user01', 'user02', 'user03');
// Pop a value atomically from a list
const username = await artillery.stash.lpop('usernames');
// Get length of a list
const length = await artillery.stash.llen('usernames');

Counters


// Increment/decrement counters atomically
const currentCount = await artillery.stash.incr('mycounter');
const newCount = await artillery.stash.decr('mycounter');

Limits

The limits described below are the default limits applied to all Stash databases. If you need to change one of the limits described below please get in touch via support@artillery.io.

Limit	Value	Notes
Database size	1 GB	Total size of data across all keys/values.
Commands	5 million / month	Each operation, such as setting or getting a value counts as one command.
Bandwidth	10 GB / month	Inbound and outbound bandwidth counts towards the limit.
Region	`us-east-1` with a read replica in `eu-west-1`	Data is stored in these regions by default.
Data retention	Indefinite	Data is not cleaned up automatically, unless TTL is set for specific keys with `stash.expire('key-name', $numberInSeconds)`

Security

Each Stash is created for & isolated to your Artillery Cloud organization.
One Stash is created for each Artillery Cloud organization, and is accessible by all of its members. We recommend using key name prefixes to help isolate data for different tests or teams.

FAQ

What happens if an Artillery Cloud API key is not provided?

When a key is not provided, or does not belong to an organization which has access to Stash API, global.artillery.stash will be set to null.

Can default limits be increased?

Yes. Send us an email on support@artillery.io with a description of the limit you’d like to change. There may be extra cost associated with the limit increase.