diff options
Diffstat (limited to 'doc/development/experiment_guide')
-rw-r--r-- | doc/development/experiment_guide/gitlab_experiment.md | 52 |
1 files changed, 48 insertions, 4 deletions
diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md index 1cd3fefb7cf..af4512dcde0 100644 --- a/doc/development/experiment_guide/gitlab_experiment.md +++ b/doc/development/experiment_guide/gitlab_experiment.md @@ -92,7 +92,7 @@ end ``` When this code executes, the experiment is run, a variant is assigned, and (if within a -controller or view) a `window.gon.experiment.pill_color` object will be available in the +controller or view) a `window.gl.experiments.pill_color` object will be available in the client layer, with details like: - The assigned variant. @@ -522,14 +522,14 @@ shared example: [tracks assignment and records the subject](https://gitlab.com/g This is in flux as of GitLab 13.10, and can't be documented just yet. -Any experiment that's been run in the request lifecycle surfaces in `window.gon.experiment`, +Any experiment that's been run in the request lifecycle surfaces in and `window.gl.experiments`, and matches [this schema](https://gitlab.com/gitlab-org/iglu/-/blob/master/public/schemas/com.gitlab/gitlab_experiment/jsonschema/1-0-0) so you can use it when resolving some concepts around experimentation in the client layer. ### Use experiments in Vue With the `gitlab-experiment` component, you can define slots that match the name of the -variants pushed to `window.gon.experiment`. For example, if we alter the `pill_color` +variants pushed to `window.gl.experiments`. For example, if we alter the `pill_color` experiment to just use the default variants of `control` and `candidate` like so: ```ruby @@ -587,7 +587,51 @@ For example, the Vue component for the previously-defined `pill_color` experimen ``` NOTE: -When there is no experiment data in the `window.gon.experiment` object for the given experiment name, the `control` slot will be used, if it exists. +When there is no experiment data in the `window.gl.experiments` object for the given experiment name, the `control` slot will be used, if it exists. + +## Test with Jest + +### Stub Helpers + +You can stub experiments using the `stubExperiments` helper defined in `spec/frontend/__helpers__/experimentation_helper.js`. + +```javascript +import { stubExperiments } from 'helpers/experimentation_helper'; +import { getExperimentData } from '~/experimentation/utils'; + +describe('when my_experiment is enabled', () => { + beforeEach(() => { + stubExperiments({ my_experiment: 'candidate' }); + }); + + it('sets the correct data', () => { + expect(getExperimentData('my_experiment')).toEqual({ experiment: 'my_experiment', variant: 'candidate' }); + }); +}); +``` + +NOTE: +This method of stubbing in Jest specs will not automatically un-stub itself at the end of the test. We merge our stubbed experiment in with all the other global data in `window.gl`. If you need to remove the stubbed experiment(s) after your test or ensure a clean global object before your test, you'll need to manage the global object directly yourself: + +```javascript +desribe('tests that care about global state', () => { + const originalObjects = []; + + beforeEach(() => { + // For backwards compatibility for now, we're using both window.gon & window.gl + originalObjects.push(window.gon, window.gl); + }); + + afterEach(() => { + [window.gon, window.gl] = originalObjects; + }); + + it('stubs experiment in fresh global state', () => { + stubExperiment({ my_experiment: 'candidate' }); + // ... + }); +}) +``` ## Notes on feature flags |