Test data sources

Read time: 14 minutes

Last edited: Aug 16, 2024

Overview

This topic explains how to use the test data source feature for more control over your LaunchDarkly SDKs during testing.

Newer versions of LaunchDarkly SDKs replace users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more, read Contexts.

Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.

About test data sources

LaunchDarkly SDKs must have a data source when they initialize. Usually, this data source is connected to LaunchDarkly. However, when you write unit tests, using a test data source can give you more control over your SDK.

LaunchDarkly supports a test data source for some SDKs. The test data source allows you to mock the behavior of a LaunchDarkly SDK so it has predictable behavior when evaluating flags.

Use the test data source for testing only

The test data source is intended strictly for testing purposes. It cannot be used in production.

You can set a flag's initial state by calling the data source's update method before or after starting the client. When you start the client, it acts as if it has connected to LaunchDarkly and received all of the test data that you have configured. Subsequent calls to update behave as if LaunchDarkly sent an update over a streaming connection.

You can modify targeting rules at any time, including when the SDK is already in use. This allows you to simulate a situation where a feature flag changes values. When you set a flag's state in the test data source, you can either set it to return a single variation for all contexts or users, or set up more complicated behavior similar to the ways you can configure a flag in the Flags list. This can be useful in testing application code that expects flags to be different for different contexts or users.

Details about each SDK's configuration are available in the SDK-specific sections below.

Client-side SDKs

This feature is available in the following client-side SDKs:

.NET (client-side)
Android

.NET (client-side)

Expand .NET (client-side) code sample

To configure the SDK to use a test data source:

using LaunchDarkly.Sdk.Client.Integrations;
var td = TestData.DataSource();
// You can set any initial flag states here with td.Update
var config = Configuration
    .Builder("mobile-key-123abc", ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .DataSource(td)
    .Build();
var client = LdClient.Init(config, context, startWaitTime);

To set a flag to a specific value:

td.Update(td.Flag("flag-key-123abc").Variation(false);

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context key "context-key-123abc" and false for everyone else
td.Update(td.Flag("flag-key-456def")
    .Variation(false)
    .VariationForKey(ContextKind.Of("user"), "context-key-123abc", true));
// This flag returns the string variation "green" for contexts where the custom
// attribute "admin" has a value of true, and "red" for all other contexts.
td.Update(td.Flag("flag-key-789ghi")
    .Variations(LdValue.Of("red"), LdValue.Of("green"))
    .VariationFunc(context =>
        context.GetValue("admin").AsBool ? 1 : 0);

To learn more, read TestData.

Android

Expand Android code sample

This feature is available in versions 4.0 and higher of the Android SDK.

To configure the SDK to use a test data source:

using com.launchdarkly.sdk.*;
using com.launchdarkly.sdk.server.*;
using com.launchdarkly.sdk.server.integrations.*;
TestData td = TestData.dataSource();
// You can set any initial flag states here with td.update
LDConfig config = new LDConfig.Builder(AutoEnvAttributes.Enabled)
  .mobileKey("mobile-key-123abc")
  .dataSource(td)
  .build();
LDClient client = LDClient.init(this.getApplication(), ldConfig, context, secondsToBlock);

To set a flag to a specific value:

td.update(td.flag("flag-key-123abc").variation(false));

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context with the key "context-key-123abc" and kind of "organization",
// and false for everyone else
td.update(td.flag("flag-key-123abc")
  .variation(false)
  .variationForKey(ContextKind.of("organization"), "context-key-123abc", true));
// This flag returns the string variation "green" for contexts who have the custom
// attribute "admin" with a value of true, and "red" for everyone else.
td.update(td.flag("flag-key-123abc")
  .variations(LDValue.of("red"), LDValue.of("green"))
  .variationFunc(context ->
    context.getValue("admin").booleanValue() ? 1 : 0));

To learn more, read TestData.

Server-side SDKs

This feature is available in the following server-side SDKs:

.NET (server-side)
C++ (server-side)
Erlang
Go
Haskell
Java
Node.js (server-side)
PHP
Python
Ruby

.NET (server-side)

Expand .NET (server-side) code sample

To configure the SDK to use a test data source:

using LaunchDarkly.Sdk.Server.Integrations;
var td = TestData.DataSource();
// You can set any initial flag states here with td.Update
var config = Configuration.Builder("sdk-key-123abc")
    .DataSource(td)
    .Build();
var client = new LdClient(config);

To set a flag to a specific value:

td.Update(td.Flag("flag-key-123abc").VariationForAll(false));

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context with the key "context-key-123abc" and kind of "organization",
// and false for everyone else
td.Update(td.Flag("flag-key-456def")
    .VariationForKey(ContextKind.Of("organization"), "context-key-123abc", true)
    .FallthroughVariation(false));
// This flag returns the string variation "green" for contexts that have the
// attribute "admin" with a value of true, and "red" for everyone else.
td.Update(td.Flag("flag-key-789ghi")
    .Variations(LdValue.Of("red"), LdValue.Of("green"))
    .FallthroughVariation(0)
    .IfMatch("admin", LdValue.Of(true))
    .ThenReturn(1));

To learn more, read TestData.

C++ (server-side)

Expand C++ (server-side) code sample

This feature is only available in v2.x of the C++ (server-side) SDK.

To configure the SDK to use a test data source:

#include <launchdarkly/integrations/test_data.h>
struct LDTestData *td = LDTestDataInit();
LDConfigSetDataSource(config, LDTestDataCreateDataSource(td));
// Call LDClientInit with config as usual.

Once you are finished using the client, ensure the test data source is freed:

// After LDClientClose:
LDTestDataFree(td)

To set a flag to a specific value:

struct LDFlagBuilder *flag = LDTestDataFlag(td, "flag-key-123abc");
LDFlagBuilderVariationForAllUsersBoolean(flag, LDBooleanTrue);
LDTestDataUpdate(td, flag);

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the user key "user-key-123abc"
// and false for everyone else.
struct LDFlagBuilder *flag2 = LDTestDataFlag(td, "flag-key-456def");
LDFlagBuilderVariationForUserBoolean(flag2, "user-key-123abc", LDBooleanTrue);
LDFlagBuilderFallthroughVariationBoolean(flag2, LDBooleanFalse);
LDTestDataUpdate(td, flag2);
// This flag returns the string variation "green" for
// users who have the custom attribute "admin" with a
// value of true, and "red" for everyone else.
struct LDJSON *variations = LDNewArray();
LDArrayPush(variations, LDNewText("red"));
LDArrayPush(variations, LDNewText("green"));
struct LDFlagBuilder *flag3 = LDTestDataFlag(td, "flag-key-789ghi");
LDFlagBuilderVariations(flag3, variations);
LDFlagBuilderFallthroughVariation(flag3, 0);
struct LDFlagRuleBuilder *rule = LDFlagBuilderIfMatch(flag3, "admin", LDNewBool(LDBooleanTrue));
LDFlagRuleBuilderThenReturn(rule, 1);
LDTestDataUpdate(td, flag3);

Erlang

Expand Erlang code sample

To configure the SDK to use a test data source:

Options = #{
  datasource => testdata,
  send_events => false,
  feature_store => ldclient_storage_map
},
ldclient:start_instance(SdkKey, Options),

To set a flag to a specific value:

{ok, Flag} = ldclient_testdata:flag("flag-key-123abc"),
ldclient_testdata:update(ldclient_flagbuilder:variation_for_all(true, Flag)),

There are other ways you can configure flag behavior using a test data source. Here is an example:

%% This flag is true for the context key "user-key-123abc" and false for everyone else
{ok, Flag2} = ldclient_testdata:flag("flag-key-456def"),
UpdatedFlag2 = ldclient_flagbuilder:fallthrough_variation(false,
  ldclient_flagbuilder:variation_for_context(true,  <<"user">>, <<"user-key-123abc">>, Flag2)
),
%% This flag returns the string variation "green" for contexts that have the custom
%% attribute "admin" with a value of true, and "red" for everyone else.
{ok, Flag} = ldclient_testdata:flag("flag-key-789ghi"),
UpdatedFlag = ldclient_flagbuilder:fallthrough_variation(0,
              ldclient_flagbuilder:then_return(1,
              ldclient_flagbuilder:if_match(<<"user">>, <<"admin">>, [true],
              ldclient_flagbuilder:variations([<<"red">>, <<"green">>], Flag)))),
ldclient_testdata:update(UpdatedFlag),

Go

Expand Go code sample

To configure the SDK to use a test data source:

import (
    ld "github.com/launchdarkly/go-server-sdk/v6"
    "github.com/launchdarkly/go-server-sdk/v6/testhelpers/ldtestdata"
    "github.com/launchdarkly/go-sdk-common/v3/ldcontext"
    "github.com/launchdarkly/go-sdk-common/v3/ldvalue"
)
td := ldtestdata.DataSource()
// You can set any initial flag states here with td.Update
config := ld.Config{
    DataSource: td,
}
client, _ := ld.MakeCustomClient("sdk-key-123abc", config, 0)

To set a flag to a specific value:

td.Update(td.Flag("flag-key-123abc").VariationForAll(false))

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context with the key "context-key-123abc" and kind of "organization",
// and false for everyone else
td.Update(td.Flag("flag-key-456def").
    VariationForKey("organization", "context-key-123abc", true).
    FallthroughVariation(false));
// This flag returns the string variation "green" for contexts that have the
// attribute "admin" with a value of true, and "red" for everyone else.
td.Update(td.Flag("flag-key-789ghi").
    Variations(ldvalue.String("red"), ldvalue.String("green")).
    FallthroughVariationIndex(0).
    IfMatch(ldcontext.GetValue("admin"), ldvalue.Bool(true)).
    ThenReturnIndex(1));

To learn more, read ldtestdata.

Haskell

Expand Haskell code sample

To configure the SDK to use a test data source:

import qualified LaunchDarkly.Server.Integrations.TestData as TestData
 td <- TestData.newTestData
 let config = LD.configSetDataSourceFactory (Just $ TestData.dataSourceFactory td) $ LD.makeConfig "sdk-key-123abc"
 client <- LD.makeClient config

To set a flag to a specific value:

TestData.update td =<< ( TestData.flag td "flag-key-123abc"
	<&> TestData.booleanFlag
	<&> TestData.variationForAll True
)

There are other ways you can configure flag behavior using a test data source. Here is an example:

-- This flag is true for the context with kind "context-kind" and key "context-key-123abc", and false for everyone else
TestData.update td =<< ( TestData.flag td "flag-key-456def"
	<&> TestData.booleanFlag
	<&> TestData.variationForKey "context-kind" "context-key-123abc" (0 :: TestData.VariationIndex)
	<&> TestData.fallthroughVariation (1 :: TestData.VariationIndex)
)
-- This flag returns the string variation "green" for contexts with kind "context-kind"
-- that have the custom attribute "admin" with a value of true, and "red" for everyone else.
TestData.update td =<< ( TestData.flag td "flag-key-456def"
	<&> TestData.variations [toJSON "red", toJSON "green"]
	<&> TestData.ifMatchContext "context-kind" "admin" [Aeson.Bool True]
	<&> TestData.thenReturn (1 :: TestData.VariationIndex)
	<&> TestData.fallthroughVariation (0 :: TestData.VariationIndex))
)

Java

Expand Java code sample

To configure the SDK to use a test data source:

using com.launchdarkly.sdk.*;
using com.launchdarkly.sdk.server.*;
using com.launchdarkly.sdk.server.integrations.*;
TestData td = TestData.dataSource();
// You can set any initial flag states here with td.update
LDConfig config = new LDConfig.Builder()
    .dataSource(td)
    .build();
LDClient client = new LDClient(sdkKey, config);

To set a flag to a specific value:

td.update(td.flag("flag-key-123abc").variationForAll(false));

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context with the key "context-key-123abc" and kind of "organization",
// and false for everyone else
td.update(td.flag("flag-key-123abc")
  .variationForKey(ContextKind.of("organization"), "context-key-123abc", true)
  .fallthroughVariation(false));
// This flag returns the string variation "green" for contexts who have the custom
// attribute "admin" with a value of true, and "red" for everyone else.
td.update(td.flag("flag-key-123abc")
  .variations(LDValue.of("red"), LDValue.of("green"))
  .fallthroughVariation(0)
  .ifMatch(ContextAttribute.forName("admin"), LDValue.of(true))
  .thenReturn(1));

To learn more, read TestData.

Node.js (server-side)

Expand Node.js (server-side) code sample

To configure the SDK to use a test data source:

const { TestData } = require('@launchdarkly/node-server-sdk/integrations');
const td = new TestData();
testData.update(td.flag('flag-key-123abc').booleanFlag().variationForAllUsers(true));
const client = new LDClient('sdk-key-123abc', { updateProcessor: td.getFactory() });
// flags can be updated at any time:
td.update(td.flag('flag-key-456def')
    .variationForUser('user-key-123abc', true)
    .fallthroughVariation(false));

To learn more, read TestData.

PHP

Expand PHP code sample

To configure the SDK to use a test data source:

require 'vendor/autoload.php';
$td = new LaunchDarkly\Integrations\TestData();
// You can set any initial flag states here with td.update
$client = new LaunchDarkly\LDClient($sdkKey, ['feature_requester' => $td]);

To set a flag to a specific value:

$td->update($td->flag("flag-key-123abc")->variationForAll(false));

There are other ways you can configure flag behavior using a test data source. Here is an example:

// This flag is true for the context with the key "context-key-123abc" and kind of "organization",
// and false for everyone else
$td->update(
    $td->flag("flag-key-123abc")
       ->variationForKey("organization", "context-key-123abc", true)
       ->fallthroughVariation(false)
);
// This flag returns the string variation "green" for contexts that have the custom
// attribute "admin" with a value of true, and "red" for everyone else.
$td->update(
    $td->flag("flag-key-123abc")
       ->variations("red", "green")
       ->fallthroughVariation(0)
       ->ifMatch("admin", true)
       ->thenReturn(1)
);

To learn more, read TestData.

Python

Expand Python code sample

To configure the SDK to use a test data source:

from ldclient.integrations.test_data import TestData
from ldclient import LDClient, Config
td = TestData.data_source()
# You can set any initial flag states here with td.update
client = LDClient(config=Config(sdk_key, update_processor_class = td))

To set a flag to a specific value:

td.update(td.flag("flag-key-123abc").variation_for_all(True))

There are other ways you can configure flag behavior using a test data source. Here is an example:

# This flag is true for the context with the key "context-key-123abc" and kind
# of "organization", and false for everyone else.
td.update(
    td.flag("flag-key-456def") \
        .variation_for_key("organization", "context-key-123abc", True) \
        .fallthrough_variation(False)
)
# This flag returns the string variation "green" for contexts of the kind "user"
# who have the custom attribute "admin" with a value of true, and "red" for
# everyone else.
td.update(
    td.flag("flag-key-789ghi") \
        .variations("red", "green")
        .fallthrough_variation(0)
        .if_match_context("user", "admin", True)
        .then_return(1)
)

To learn more, read TestData.

Ruby

Expand Ruby code sample

To configure the SDK to use a test data source:

require 'ldclient-rb'
td = LaunchDarkly::Integrations::TestData.data_source
# You can set any initial flag states here with td.update
config = LaunchDarkly::Config.new(data_source = td)
client = LaunchDarkly::LDClient.new(sdk_key, config)

To set a flag to a specific value:

td.update(td.flag("flag-key-123abc").variation_for_all(false))

There are other ways you can configure flag behavior using a test data source. Here is an example:

# This flag is true for the context key "context-key-123abc" and false for everyone else
td.update(td.flag("flag-key-456def").
    variation_for_user("context-key-123abc", true).
    fallthrough_variation(false))
# This flag returns the string variation "green" for contexts who have the custom
# attribute "admin" with a value of true, and "red" for everyone else.
td.update(td.flag("flag-key-789ghi").
    variations("red", "green").
    fallthrough_variation(0).
    if_match_context("user", "admin", true).then_return(1))

To learn more, read TestData.

Test data sources

Read time: 14 minutes

Last edited: Aug 16, 2024

.css-1wc0auy{padding-right:0.5rem;margin-left:-2rem;float:left;display:none;}@media screen and (min-width: 48rem){.css-1wc0auy{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;}}Overview

About test data sources

Client-side SDKs

.NET (client-side)

Android

Server-side SDKs

.NET (server-side)

C++ (server-side)

Erlang

Go

Haskell

Java

Node.js (server-side)

PHP

Python

Ruby

Overview