Skip to content

Commit

Permalink
docs: update playground docs to mention advanced features (#4266)
Browse files Browse the repository at this point in the history
This change updates the playground reference docs with some new images
and an explanation of how the results work now.

I have not removed any of the old images because I think they still
illustrate well how the playground works. And because they're not
direct screenshots anyway, that sounds like a fair trade-off to me.
  • Loading branch information
thomasheartman committed Jul 18, 2023
1 parent 3ee9c4b commit 35fbd8f
Show file tree
Hide file tree
Showing 4 changed files with 33 additions and 5 deletions.
38 changes: 33 additions & 5 deletions website/docs/reference/playground.mdx
@@ -1,10 +1,11 @@
---
title: The Playground
---
import Figure from '@site/src/components/Figure/Figure.tsx'

:::info Availability

The Unleash playground is available from Unleash 4.14 onwards. The playground is available in all Unleash versions.
The Unleash playground is available in all Unleash versions from Unleash 4.14 onwards. Unleash 5.3 introduced a more advanced playground that allows you to query multiple environments and multiple values for a single context value at the same time.

:::

Expand All @@ -22,18 +23,30 @@ Each feature toggle will contain info on whether it was enabled or not and which

This section describes what information the playground needs to evaluate your Unleash context against your existing features.

### Environment and projects
### Environments and projects

The playground needs to know which environment and which projects to use when evaluating features. The playground UI will default to using the first environment in your list of instance environments and all projects.
The playground needs to know which environments and which projects to use when evaluating features. The playground UI will default to using the first environment in your list of instance environments and all projects.

Features can only be evaluated against a single environment at a time. The environment should be one of the environments configured for your Unleash instance.
You can select as many of your environments as you want. All environments must be environments that exist in your Unleash instance. Prior to Unleash 5.3, features could only be evaluated against a single environment at a time.

The playground will only evaluate features belonging to the projects you specify. The projects parameter can either be a list of projects **or** _all_ projects.

### The Unleash context

The [Unleash context](../reference/unleash-context.md) represents a client SDK's configuration and used for evaluating your features. You can construct your own context or use a JSON version of a context from a client.

#### Multiple values for a single context field

:::info Availability

The ability to specifiy multiple values for a single context field was introduced in Unleash 5.3.

:::

You can specify multiple values for a single context field by separating the values with a comma. For instance: `"value1, value2"`.

When you specify multiple values for context field, each value will be used to populate one variant of the response.

#### Implicit context fields

You can add any fields you want to the context used for the evaluation, and you can also leave out any fields you want. However, there are some fields that will be set for you if don't provide them:
Expand All @@ -45,10 +58,25 @@ You can add any fields you want to the context used for the evaluation, and you

![Playground results: a table of feature names and whether they're enabled or not.](/img/playground-results.png)

The playground's response contains a list of all the feature toggles that have been evaluated based on your configured [environments and projects](#environments-and-projects). In the UI, the playground displays the features in a table. Each feature indicates whether its considered _enabled_ or _disabled_ and which [variant](../reference/feature-toggle-variants.md) was assigned to it, if any.
The playground's response contains a list of all the feature toggles that have been evaluated based on your configured [environments, projects](#environments-and-projects) and [context](#the-unleash-context). The full response will contain results for all combinations of context fields and all environments that you selected.

In the UI, the playground displays the features in a table. Each row of the table corresponds to a single feature. The table has a separate column for each of the environments that you selected for your query.

<Figure caption='Each row contains a feature and columns for the selected environments. In this screenshot, the "development" and "production" environments have been selected.' img="/img/playground-results-row.png"/>

Because you can add multiple values for each context field, each feature-environment cell contains the number of combinations that evaluated to `true` and `false` for the feature in the given environment. This can be expanded into a more detailed overview over what combinations of context fields evaluated to `true` and `false` along with any [variants](../reference/feature-toggle-variants.md).

<Figure caption='A small table showing the detailed evaluation for a feature in the "development" environment. The provided context contained three values for the "userId" property, so the table contains three rows, showing all different combinations of the context.' img="/img/playground-results-development.png"/>

As with all of Unleash's client SDKs, the playground respects [stickiness](../reference/stickiness.md). The [stickiness algorithm](../reference/stickiness.md#calculation) guarantees that you'll always get the same variants and the same gradual rollout results if you provide the same context, as long as you provide the context field used for calculating stickiness.

### The diff view

You can compare how a feature evaluates in different environments. If you select more than one environment for your playground query, the table will have an additional "Diff" column in each row. Using the "preview diff" button, you can open a table that gives an overview over how the feature evaluated for each context combination in each environment.

<Figure caption='A table with three rows. Each row contains a context combination and results in the form of `true` and `false` each environment. In this case, it shows that when the "userId" context field is "2", then the feature is enabled in development, but not in production.' img="/img/playground-results-diff.png"/>


### Detailed evaluation results

:::info Availability
Expand Down
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/static/img/playground-results-diff.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/static/img/playground-results-row.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 35fbd8f

Please sign in to comment.