Test fixtures

ldclient.integrations.test_data module

The entry point for this feature is ldclient.integrations.test_data.TestData.

class ldclient.integrations.test_data.FlagBuilder(key: str)

Bases: object

A builder for feature flag configurations to be used with ldclient.integrations.test_data.TestData.

See:

ldclient.integrations.test_data.TestData.flag()

See:

ldclient.integrations.test_data.TestData.update()

__init__(key: str)

Parameters:

key (str) – The name of the flag

boolean_flag() → FlagBuilder

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

This is the default for all new flags created with ldclient.integrations.test_data.TestData.flag().

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.

Returns:

the flag builder

clear_rules() → FlagBuilder

Removes any existing rules from the flag. This undoes the effect of methods like ldclient.integrations.test_data.FlagBuilder.if_match().

Returns:

the same flag builder

clear_targets() → FlagBuilder

Removes any existing targets from the flag. This undoes the effect of methods like ldclient.integrations.test_data.FlagBuilder.variation_for_user().

Returns:

the same flag builder

fallthrough_variation(variation: bool | int) → FlagBuilder

Specifies the fallthrough variation. 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 and the variation specified is a boolean, this also changes it to a boolean flag.

Parameters:

variation (bool|int) – True or False or the desired fallthrough variation index: 0 for the first, 1 for the second, etc.

Returns:

the flag builder

if_match(attribute: str, *values) → FlagRuleBuilder

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

This is a shortcut for calling ldclient.integrations.test_data.FlagBuilder.if_match_context() with “user” as the context kind.

Example: create a rule that returns True if the name is “Patsy” or “Edina”

td.flag("flag") \
    .if_match('name', 'Patsy', 'Edina') \
    .then_return(True)

Parameters:

• attribute – the user attribute to match against

• values – values to compare to

Returns:

the flag rule builder

if_match_context(context_kind: str, attribute: str, *values) → FlagRuleBuilder

Starts defining a flag rule, using the “is one of” operator. This matching expression only applies to contexts of a specific kind.

Example: create a rule that returns True if the name attribute for the company” context is “Ella” or “Monsoon”:

td.flag("flag") \
    .if_match_context('company', 'name', 'Ella', 'Monsoon') \
    .then_return(True)

Parameters:

• context_kind – the context kind

• attribute – the context attribute to match against

• values – values to compare to

Returns:

the flag rule builder

if_not_match(attribute: str, *values) → FlagRuleBuilder

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

This is a shortcut for calling ldclient.integrations.test_data.FlagBuilder.if_not_match_context() with “user” as the context kind.

Example: create a rule that returns True if the name is neither “Saffron” nor “Bubble”

td.flag("flag") \
    .if_not_match('name', 'Saffron', 'Bubble') \
    .then_return(True)

Parameters:

• attribute – the user attribute to match against

• values – values to compare to

Returns:

the flag rule builder

if_not_match_context(context_kind: str, attribute: str, *values) → FlagRuleBuilder

Starts defining a flag rule, using the “is not one of” operator. This matching expression only applies to contexts of a specific kind.

Example: create a rule that returns True if the name attribute for the “company” context is neither “Pendant” nor “Sterling Cooper”:

td.flag("flag") \
    .if_not_match('company', 'name', 'Pendant', 'Sterling Cooper') \
    .then_return(True)

Parameters:

• context_kind – the context kind

• attribute – the context attribute to match against

• values – values to compare to

Returns:

the flag rule builder

off_variation(variation: bool | int) → FlagBuilder

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

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

Parameters:

variation (bool|int) – True or False or the desired off variation index: 0 for the first, 1 for the second, etc.

Returns:

the flag builder

on(on: bool) → FlagBuilder

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 ldclient.integrations.test_data.TestData.flag() with a new flag key, the flag will return False whenever targeting is off, and True when targeting is on.

Parameters:

on – True if targeting should be on

Returns:

the flag builder

value_for_all(value: Any) → FlagBuilder

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

The value may be of any JSON type. 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.

:param value the desired value to be returned for all users :return the flag builder

variation_for_all(variation: bool | int) → FlagBuilder

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

The variation is specified, 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.

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

Parameters:

variation (bool|int) – True or False or the desired variation index to return: 0 for the first, 1 for the second, etc.

Returns:

the flag builder

variation_for_key(context_kind: str, context_key: str, variation: bool | int) → FlagBuilder

Sets the flag to return the specified variation for a specific context, identified by context kind and key, when targeting is on.

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

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

Parameters:

• context_kind – the context kind

• context_key – the context key

• variation (bool|int) – True or False or the desired variation index to return: 0 for the first, 1 for the second, etc.

Returns:

the flag builder

variation_for_user(user_key: str, variation: bool | int) → FlagBuilder

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.

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

Parameters:

• user_key – a user key

• variation (bool|int) – True or False or the desired variation index to return: 0 for the first, 1 for the second, etc.

Returns:

the flag builder

variations(*variations) → FlagBuilder

Changes the allowable variation values for the flag.

The value may be of any valid JSON type. For instance, a boolean flag normally has True, False; a string-valued flag might have 'red', 'green'; etc.

Example: A single variation

td.flag('new-flag').variations(True)

Example: Multiple variations

td.flag('new-flag').variations('red', 'green', 'blue')

Parameters:

variations – the the desired variations

Returns:

the flag builder

class ldclient.integrations.test_data.FlagRuleBuilder(flag_builder: FlagBuilder)

Bases: object

A builder for feature flag rules to be used with ldclient.integrations.test_data.FlagBuilder.

In the LaunchDarkly model, a flag can have any number of rules, and a rule can have any number of clauses. A clause is an individual test such as “name is ‘X’”. A rule matches a user if all of the rule’s clauses match the user.

To start defining a rule, use one of the flag builder’s matching methods such as ldclient.integrations.test_data.FlagBuilder.if_match(). This defines the first clause for the rule. Optionally, you may add more clauses with the rule builder’s methods such as ldclient.integrations.test_data.FlagRuleBuilder.and_match() or ldclient.integrations.test_data.FlagRuleBuilder.and_not_match(). Finally, call ldclient.integrations.test_data.FlagRuleBuilder.then_return() to finish defining the rule.

__init__(flag_builder: FlagBuilder)

and_match(attribute: str, *values) → FlagRuleBuilder

Adds another clause, using the “is one of” operator.

This is a shortcut for calling ldclient.integrations.test_data.FlagRuleBuilder.and_match_context() with “user” as the context kind.

Example: create a rule that returns True if the name is “Patsy” and the country is “gb”

td.flag('flag') \
    .if_match('name', 'Patsy') \
    .and_match('country', 'gb') \
    .then_return(True)

Parameters:

• attribute – the user attribute to match against

• values – values to compare to

Returns:

the flag rule builder

and_match_context(context_kind: str, attribute: str, *values) → FlagRuleBuilder

Adds another clause, using the “is one of” operator. This matching expression only applies to contexts of a specific kind.

Example: create a rule that returns True if the name attribute for the “company” context is “Ella”, and the country attribute for the “company” context is “gb”:

td.flag('flag') \
    .if_match_context('company', 'name', 'Ella') \
    .and_match_context('company', 'country', 'gb') \
    .then_return(True)

Parameters:

• context_kind – the context kind

• attribute – the context attribute to match against

• values – values to compare to

Returns:

the flag rule builder

and_not_match(attribute: str, *values) → FlagRuleBuilder

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

This is a shortcut for calling ldclient.integrations.test_data.FlagRuleBuilder.and_not_match_context() with “user” as the context kind.

Example: create a rule that returns True if the name is “Patsy” and the country is not “gb”

td.flag('flag') \
    .if_match('name', 'Patsy') \
    .and_not_match('country', 'gb') \
    .then_return(True)

Parameters:

• attribute – the user attribute to match against

• values – values to compare to

Returns:

the flag rule builder

and_not_match_context(context_kind: str, attribute: str, *values) → FlagRuleBuilder

Adds another clause, using the “is not one of” operator. This matching expression only applies to contexts of a specific kind.

Example: create a rule that returns True if the name attribute for the “company” context is “Ella”, and the country attribute for the “company” context is not “gb”:

td.flag('flag') \
    .if_match_context('company', 'name', 'Ella') \
    .and_not_match_context('company', 'country', 'gb') \
    .then_return(True)

Parameters:

• context_kind – the context kind

• attribute – the context attribute to match against

• values – values to compare to

Returns:

the flag rule builder

then_return(variation: bool | int) → FlagBuilder

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

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

Parameters:

variation (bool|int) – True or False or the desired variation index: 0 for the first, 1 for the second, etc.

Returns:

the flag builder with this rule added

class ldclient.integrations.test_data.TestData

Bases: object

A mechanism for providing dynamically updatable feature flag state in a simplified form to an SDK client in test scenarios.

Unlike Files, this mechanism does not use any external resources. It provides only the data that the application has put into it using the update method.

td = TestData.data_source()
td.update(td.flag('flag-key-1').variation_for_all(True))

client = LDClient(config=Config('SDK_KEY', update_processor_class = td))

# flags can be updated at any time:
td.update(td.flag('flag-key-1'). \
    variation_for_user('some-user-key', True). \
    fallthrough_variation(False))

The above example uses a simple boolean flag, but more complex configurations are possible using the methods of the FlagBuilder that is returned by flag. FlagBuilder supports many of the ways a flag can be configured on the LaunchDarkly dashboard, but does not currently support 1. rule operators other than “in” and “not in”, or 2. percentage rollouts.

If the same TestData instance is used to configure multiple LDClient instances, any changes made to the data will propagate to all of the LDClient instances.

__init__()

static data_source() → TestData

Creates a new instance of the test data source.

Returns:

a new configurable test data source

flag(key: str) → FlagBuilder

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

If this flag key has already been defined in this TestData 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 FlagBuilder methods.

Once you have set the desired configuration, pass the builder to update.

Parameters:

key (str) – the flag key

Returns:

the flag configuration builder object

update(flag_builder: FlagBuilder) → TestData

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 TestData. 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 FlagBuilder instance do not affect the test data, unless you call update again.

Parameters:

flag_builder – a flag configuration builder

Returns:

self (the TestData object)