test_data.h File Reference

Public API for LDTestData. More...

#include <stdio.h>
#include <stdarg.h>
#include <launchdarkly/boolean.h>
#include <launchdarkly/export.h>
#include <launchdarkly/json.h>
#include <launchdarkly/data_source.h>

Include dependency graph for test_data.h:

Go to the source code of this file.

Functions
struct LDTestData *	LDTestDataInit (void)
	Creates a new instance of the LDTestData data source. More...
void	LDTestDataFree (struct LDTestData *testData)
	Free all of the data associated with the test data source. More...
struct LDFlagBuilder *	LDTestDataFlag (struct LDTestData *testData, const char *key)
	Creates or copies a LDFlagBuilder for building a test flag configuration. More...
LDBoolean	LDTestDataUpdate (struct LDTestData *testData, struct LDFlagBuilder *flagBuilder)
	Updates the test data with the specified flag configuration. More...
struct LDDataSource *	LDTestDataCreateDataSource (struct LDTestData *)
	Create a LDDataSource instance to be used in a client config. More...
LDBoolean	LDFlagBuilderBooleanFlag (struct LDFlagBuilder *flagBuilder)
	A shortcut for setting the flag to use the standard boolean configuration. More...
void	LDFlagBuilderOn (struct LDFlagBuilder *flagBuilder, LDBoolean on)
	Sets targeting to be on or off for this flag. More...
void	LDFlagBuilderFallthroughVariation (struct LDFlagBuilder *flagBuilder, int variationIndex)
	Specifies the index of the fallthrough variation. More...
LDBoolean	LDFlagBuilderFallthroughVariationBoolean (struct LDFlagBuilder *flagBuilder, LDBoolean value)
	Specifies the fallthrough variation for a boolean flag. More...
void	LDFlagBuilderOffVariation (struct LDFlagBuilder *flagBuilder, int variationIndex)
	Specifies the index of the off variation. More...
LDBoolean	LDFlagBuilderOffVariationBoolean (struct LDFlagBuilder *flagBuilder, LDBoolean value)
	Specifies the off variation for a boolean flag. More...
void	LDFlagBuilderVariationForAllUsers (struct LDFlagBuilder *flagBuilder, int variationIndex)
	Sets the flag to always return the specified variation for all users. More...
LDBoolean	LDFlagBuilderVariationForAllUsersBoolean (struct LDFlagBuilder *flagBuilder, LDBoolean value)
	Sets the flag to always return the specified boolean variation for all users. More...
void	LDFlagBuilderValueForAllUsers (struct LDFlagBuilder *flagBuilder, struct LDJSON *value)
	Sets the flag to always return the specified variation value for all users. More...
LDBoolean	LDFlagBuilderVariationForUser (struct LDFlagBuilder *flagBuilder, const char *userKey, int variationIndex)
	Sets the flag to return the specified variation for a specific user key when targeting is on. More...
LDBoolean	LDFlagBuilderVariationForUserBoolean (struct LDFlagBuilder *flagBuilder, const char *userKey, LDBoolean value)
	Sets the flag to return the specified boolean variation for a specific user key when targeting is on. More...
LDBoolean	LDFlagBuilderVariations (struct LDFlagBuilder *flagBuilder, struct LDJSON *variations)
struct LDFlagRuleBuilder *	LDFlagBuilderIfMatch (struct LDFlagBuilder *flagBuilder, const char *const attribute, struct LDJSON *values)
	Starts defining a flag rule, using the "is one of" operator. More...
struct LDFlagRuleBuilder *	LDFlagBuilderIfNotMatch (struct LDFlagBuilder *flagBuilder, const char *const attribute, struct LDJSON *values)
	Starts defining a flag rule, using the "is not one of" operator. More...
LDBoolean	LDFlagRuleBuilderAndMatch (struct LDFlagRuleBuilder *ruleBuilder, const char *const attribute, struct LDJSON *values)
	Adds another clause, using the "is one of" operator. More...
LDBoolean	LDFlagRuleBuilderAndNotMatch (struct LDFlagRuleBuilder *ruleBuilder, const char *const attribute, struct LDJSON *values)
	Adds another clause, using the "is not one of" operator. More...
void	LDFlagRuleBuilderThenReturn (struct LDFlagRuleBuilder *ruleBuilder, int variationIndex)
	Finishes defining the rule, specifying the result as a variation index. More...
LDBoolean	LDFlagRuleBuilderThenReturnBoolean (struct LDFlagRuleBuilder *ruleBuilder, LDBoolean value)
	Finishes defining the rule, specifying the result value as a boolean. More...

Detailed Description

Public API for LDTestData.

Function Documentation

LDFlagBuilderBooleanFlag()

LDBoolean LDFlagBuilderBooleanFlag

(

struct LDFlagBuilder *

flagBuilder

)

A shortcut for setting the flag to use the standard boolean configuration.

This is the default for all new flags created with LDTestDataFlag(). The flag will have two variations, true and false (in that order); it will return false whenever targeting is off, and true when targeting is on if no other settings specify otherwise.

Parameters

[in]

flagBuilder

The flag configuration builder.

Returns

True on success, False on failure.

LDFlagBuilderFallthroughVariation()

void LDFlagBuilderFallthroughVariation	(	struct LDFlagBuilder *	flagBuilder,
		int	variationIndex
	)

Specifies the index of the fallthrough variation.

The fallthrough is the variation that is returned if targeting is on and the user was not matched by a more specific target or rule.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	variationIndex	the desired fallthrough variation: 0 for the first, 1 for the second, etc.

Returns

void

LDFlagBuilderFallthroughVariationBoolean()

LDBoolean LDFlagBuilderFallthroughVariationBoolean	(	struct LDFlagBuilder *	flagBuilder,
		LDBoolean	value
	)

Specifies the fallthrough variation for a boolean flag.

The fallthrough is the value that is returned if targeting is on and the user was not matched by a more specific target or rule.

If the flag was previously configured with other variations, this also changes it to a boolean flag.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	value	true if the flag should return true by default when targeting is on

Returns

True on success, False on failure.

LDFlagBuilderIfMatch()

struct LDFlagRuleBuilder* LDFlagBuilderIfMatch	(	struct LDFlagBuilder *	flagBuilder,
		const char *const	attribute,
		struct LDJSON *	values
	)

Starts defining a flag rule, using the "is one of" operator.

For example, this creates a rule that returns true if the name is "Patsy" or "Edina":

struct LDJSON *names;
struct LDFlagBuilder *flag;
struct LDFlagRuleBuilder *rule;
 
flag = LDTestDataFlag(testData, "flag");
names = LDNewArray();
LDArrayPush(names, LDNewText("Patsy"));
LDArrayPush(names, LDNewText("Edina"));
rule = LDFlagBuilderIfMatch(flag, "name", names);
LDFlagRuleBuilderThenReturnBoolean(rule, LDBooleanTrue);

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	attribute	the user attribute to match against
[in]	values	values to compare to

Returns

a LDFlagRuleBuilder; call LDFlagRuleBuilderThenReturn or LDFlagRuleBuilderThenReturnBoolean to finish the rule, or add more tests with another method like LDFlagRuleBuilderAndMatch; Ownership is not transferred.

LDFlagBuilderIfNotMatch()

struct LDFlagRuleBuilder* LDFlagBuilderIfNotMatch	(	struct LDFlagBuilder *	flagBuilder,
		const char *const	attribute,
		struct LDJSON *	values
	)

Starts defining a flag rule, using the "is not one of" operator.

For example, this creates a rule that returns true if the name is neither "Saffron" nor "Bubble":

struct LDJSON *names;
struct LDFlagBuilder *flag;
struct LDFlagRuleBuilder *rule;
 
flag = LDTestDataFlag(testData, "flag");
names = LDNewArray();
LDArrayPush(names, LDNewText("Saffron"));
LDArrayPush(names, LDNewText("Bubble"));
rule = LDFlagBuilderIfNotMatch(flag, "name", names);
LDFlagRuleBuilderThenReturnBoolean(rule, LDBooleanTrue);

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	attribute	the user attribute to match against
[in]	values	values to compare to

Returns

a LDFlagRuleBuilder; call LDFlagRuleBuilderThenReturn or LDFlagRuleBuilderThenReturnBoolean to finish the rule, or add more tests with another method like LDFlagRuleBuilderAndMatch; Ownership is not transferred.

LDFlagBuilderOffVariation()

void LDFlagBuilderOffVariation	(	struct LDFlagBuilder *	flagBuilder,
		int	variationIndex
	)

Specifies the index of the off variation.

This is the variation that is returned whenever targeting is off.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	variationIndex	the desired fallthrough variation: 0 for the first, 1 for the second, etc.

Returns

void

LDFlagBuilderOffVariationBoolean()

LDBoolean LDFlagBuilderOffVariationBoolean	(	struct LDFlagBuilder *	flagBuilder,
		LDBoolean	value
	)

Specifies the off variation for a boolean flag.

This is the variation that is returned whenever targeting is off.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	value	true if the flag should return true by default when targeting is on

Returns

True on success, False on failure.

LDFlagBuilderOn()

void LDFlagBuilderOn	(	struct LDFlagBuilder *	flagBuilder,
		LDBoolean	on
	)

Sets targeting to be on or off for this flag.

The effect of this depends on the rest of the flag configuration, just as it does on the real LaunchDarkly dashboard. In the default configuration that you get from calling LDTestDataFlag() with a new flag key, the flag will return false whenever targeting is off, and true when targeting is on.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	on	LDBooleanTrue if targeting should be on

Returns

void

LDFlagBuilderValueForAllUsers()

void LDFlagBuilderValueForAllUsers	(	struct LDFlagBuilder *	flagBuilder,
		struct LDJSON *	value
	)

Sets the flag to always return the specified variation value for all users.

The value may be of any JSON type, as defined by LDJSON. This method changes the flag to have only a single variation, which is this value, and to return the same variation regardless of whether targeting is on or off. Any existing targets or rules are removed.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	value	the desired value to be returned for all users; Ownership of value is transferred.

Returns

void

LDFlagBuilderVariationForAllUsers()

void LDFlagBuilderVariationForAllUsers	(	struct LDFlagBuilder *	flagBuilder,
		int	variationIndex
	)

Sets the flag to always return the specified variation for all users.

The variation is specified by number, out of whatever variation values have already been defined. Targeting is switched on, and any existing targets or rules are removed. The fallthrough variation is set to the specified value. The off variation is left unchanged.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	variationIndex	the desired fallthrough variation: 0 for the first, 1 for the second, etc.

Returns

void

LDFlagBuilderVariationForAllUsersBoolean()

LDBoolean LDFlagBuilderVariationForAllUsersBoolean	(	struct LDFlagBuilder *	flagBuilder,
		LDBoolean	value
	)

Sets the flag to always return the specified boolean variation for all users.

Targeting is switched on, any existing targets or rules are removed, and the flag's variations are set to true and false. The fallthrough variation is set to the specified value. The off variation is left unchanged.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	variation	the desired true/false variation to be returned for all users

Returns

True on success, False on failure.

LDFlagBuilderVariationForUser()

LDBoolean LDFlagBuilderVariationForUser	(	struct LDFlagBuilder *	flagBuilder,
		const char *	userKey,
		int	variationIndex
	)

Sets the flag to return the specified variation for a specific user key when targeting is on.

This has no effect when targeting is turned off for the flag.

The variation is specified by number, out of whatever variation values have already been defined.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	userKey	a user key
[in]	variationIndex	the desired variation to be returned for this user when targeting is on: 0 for the first, 1 for the second, etc.

Returns

void

LDFlagBuilderVariationForUserBoolean()

LDBoolean LDFlagBuilderVariationForUserBoolean	(	struct LDFlagBuilder *	flagBuilder,
		const char *	userKey,
		LDBoolean	value
	)

Sets the flag to return the specified boolean variation for a specific user key when targeting is on.

This has no effect when targeting is turned off for the flag.

If the flag was not already a boolean flag, this also changes it to a boolean flag.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	userKey	a user key
[in]	variation	the desired true/false variation to be returned for this user when targeting is on

Returns

True on success, False on failure.

LDFlagBuilderVariations()

LDBoolean LDFlagBuilderVariations	(	struct LDFlagBuilder *	flagBuilder,
		struct LDJSON *	variations
	)

Changes the allowable variation values for the flag.

The value may be of any JSON type, as defined by LDJSON. For instance, a boolean flag normally has an LDArray containing LDNewBoolean(LDBooleanTrue), LDNewBoolean(LDBooleanFalse); a string-valued flag might have an LDArray containing LDNewText("red"), LDNewText("green"); etc.

Parameters

[in]	flagBuilder	The flag configuration builder.
[in]	variations	the desired variations; Ownership of variations is transferred.

Returns

True on success, False on failure.

LDFlagRuleBuilderAndMatch()

LDBoolean LDFlagRuleBuilderAndMatch	(	struct LDFlagRuleBuilder *	ruleBuilder,
		const char *const	attribute,
		struct LDJSON *	values
	)

Adds another clause, using the "is one of" operator.

For example, this creates a rule that returns true if the name is "Patsy" and the country is "gb":

struct LDFlagBuilder *flag;
struct LDFlagRuleBuilder *rule;
 
flag = LDTestDataFlag(testData, "flag");
rule = LDFlagBuilderIfMatch(flag, "name", LDNewText("Patsy"));
LDFlagRuleBuilderAndMatch(rule, "country", LDNewText("gb"));
LDFlagRuleBuilderThenReturnBoolean(rule, LDBooleanTrue);

Parameters

[in]	ruleBuilder	the rule builder
[in]	attribute	the user attribute to match against
[in]	values	values to compare to

Returns

True on success, False on failure.

LDFlagRuleBuilderAndNotMatch()

LDBoolean LDFlagRuleBuilderAndNotMatch	(	struct LDFlagRuleBuilder *	ruleBuilder,
		const char *const	attribute,
		struct LDJSON *	values
	)

Adds another clause, using the "is not one of" operator.

For example, this creates a rule that returns true if the name is "Patsy" and the country is not "gb":

struct LDFlagBuilder *flag;
struct LDFlagRuleBuilder *rule;
 
flag = LDTestDataFlag(testData, "flag");
rule = LDFlagBuilderIfMatch(flag, "name", LDNewText("Patsy"));
LDFlagRuleBuilderAndNotMatch(rule, "country", LDNewText("gb"));
LDFlagRuleBuilderThenReturnBoolean(rule, LDBooleanTrue);

Parameters

[in]	ruleBuilder	the rule builder
[in]	attribute	the user attribute to match against
[in]	values	values to compare to

Returns

True on success, False on failure.

LDFlagRuleBuilderThenReturn()

void LDFlagRuleBuilderThenReturn	(	struct LDFlagRuleBuilder *	ruleBuilder,
		int	variationIndex
	)

Finishes defining the rule, specifying the result as a variation index.

Parameters

[in]	ruleBuilder	the rule builder
[in]	variationIndex	the variation to return if the rule matches the user: 0 for the first, 1 for the second, etc.

Returns

void

LDFlagRuleBuilderThenReturnBoolean()

LDBoolean LDFlagRuleBuilderThenReturnBoolean	(	struct LDFlagRuleBuilder *	ruleBuilder,
		LDBoolean	value
	)

Finishes defining the rule, specifying the result value as a boolean.

Parameters

[in]	ruleBuilder	the rule builder
[in]	variation	the value to return if the rule matches the user

Returns

True on success, False on failure.

LDTestDataCreateDataSource()

struct LDDataSource* LDTestDataCreateDataSource

(

struct LDTestData *

)

Create a LDDataSource instance to be used in a client config.

Parameters

[in]

testData

the LDTestData instance

Returns

a data source to be used with LDConfigSetDataSource

See also

LDConfigSetDataSource

LDTestDataFlag()

struct LDFlagBuilder* LDTestDataFlag	(	struct LDTestData *	testData,
		const char *	key
	)

Creates or copies a LDFlagBuilder for building a test flag configuration.

If this flag key has already been defined in this LDTestData instance, then the builder starts with the same configuration that was last provided for this flag.

Otherwise, it starts with a new default configuration in which the flag has true and false variations, is true for all users when targeting is turned on and false otherwise, and currently has targeting turned on. You can change any of those properties, and provide more complex behavior, using the LDFlagBuilder functions.

Once you have set the desired configuration, pass the builder to LDTestDataUpdate().

Parameters

[in]	testData	the LDTestData instance
[in]	key	the flag key

Returns

a flag configuration builder

See also

LDTestDataUpdate

LDTestDataFree()

void LDTestDataFree

(

struct LDTestData *

testData

)

Free all of the data associated with the test data source.

Parameters

[in]

testData

May be NULL.

Returns

Void.

LDTestDataInit()

struct LDTestData* LDTestDataInit

(

void

)

Creates a new instance of the LDTestData data source.

Returns

a new configurable test data source

LDTestDataUpdate()

LDBoolean LDTestDataUpdate	(	struct LDTestData *	testData,
		struct LDFlagBuilder *	flagBuilder
	)

Updates the test data with the specified flag configuration.

This has the same effect as if a flag were added or modified on the LaunchDarkly dashboard. It immediately propagates the flag change to any LDClient instance(s) that you have already configured to use this LDTestData. If no LDClient has been started yet, it simply adds this flag to the test data which will be provided to any LDClient that you subsequently configure.

Any subsequent changes to this LDFlagBuilder instance do not affect the test data, unless you call LDTestDataUpdate again.

Parameters

[in]	testData	the LDTestData instance
[in]	flagBuilder	a flag configuration builder. Ownership of flagBuilder is transferred.

Returns

True on success, False on failure.

See also

LDTestDataFlag