Skip to content

Commit 8750857

Browse files
JakeiiJakeii
authored
move beta ab test docs to the bottom, emphasise the beta-ness (#14768)
1 parent b82228c commit 8750857

File tree

1 file changed

+82
-81
lines changed

1 file changed

+82
-81
lines changed

‎dotcom-rendering/docs/development/ab-testing-in-dcr.md‎

Lines changed: 82 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -2,87 +2,7 @@
22

33
This document explains how to set up A/B tests in Dotcom Rendering (DCR).
44

5-
## Creating a new A/B test
6-
7-
Create an ab test in [ab-testing/abTest.ts](../ab-testing/abTest.ts) both server and client side tests are defined here. More information on defining tests can be found in [ab-testing/README.md](../ab-testing/README.md).
8-
9-
When the config is merged, the A/B test will be automatically deployed and be available at the same time as your changes.
10-
11-
Ab test on/off state is controlled only by the config. Expired tests will cause the ab testing validation to fail, they will also not be served. In effect expired tests are turned off "automatically", but their config needs to be cleaned up.
12-
13-
The test will appear in https://frontend.gutools.co.uk/analytics/ab-testing once the config is deployed.
14-
15-
## Putting code changes behind an A/B test (group)
16-
17-
### Use in Components
18-
19-
Again, this applies to both client and server side tests.
20-
21-
```ts
22-
// Within the components
23-
import { useBetaAB } from '../lib/useAB';
24-
25-
const someComponent = () => {
26-
// Example usage of AB Tests
27-
const abTests = useBetaAB();
28-
29-
// Am I in the test at all?
30-
const isInTest = abTests?.isUserInTest('AbTestTest') ?? false;
31-
32-
const isInControlGroup =
33-
(abTests?.isUserInTestGroup('AbTestTest', 'control') ?? false);
34-
35-
const isInVariantGroup =
36-
abTests?.isUserInTestGroup('AbTestTest', 'variant') ?? false;
37-
38-
if (isInControlGroup) {
39-
return (
40-
<div>
41-
You're in the control group
42-
</div>
43-
);
44-
} else if (isInVariantGroup) {
45-
return (
46-
<div>
47-
You're in the variant group
48-
</div>
49-
);
50-
} else {
51-
return (
52-
<div>
53-
You're not in the test
54-
</div>
55-
);
56-
}
57-
}
58-
59-
```
60-
61-
### Other ways to check
62-
63-
The ab test API is also available on the window object as `window.guardian.modules.abTests`, this only works client side. It's best to use the `useBetaAB` hook in react components.
64-
65-
Server side tests are also available in the CAPI object e.g. `CAPIArticle.config.serverSideABTests`.
66-
67-
## Forcing yourself into a test
68-
69-
Use the opt-in and opt-out URL fragments to force yourself into or out of a test.
70-
71-
When opted-in, the test will override any mvt based assignment and you'll only be in the opted-in test group.
72-
73-
When opted-out, you'll return to random/mvt based assignment.
74-
75-
These links are also in the [frontend admin](https://frontend.gutools.co.uk/analytics/ab-testing).
76-
77-
- Opt-in Example: `https://theguardian.com/ab-tests/opt/in/commercial-test-example:variant`
78-
- Opt-out: `https://theguardian.com/ab-tests/opt/out`
79-
80-
# Legacy A/B testing in DCR
81-
82-
> [!WARNING]
83-
> This section describes the legacy A/B testing framework in DCR. New A/B tests should use the new A/B testing framework described above.
84-
85-
The documentation remains here for reference, until all legacy A/B tests have ended or have been migrated to the new framework.
5+
There's a new beta A/B testing framework in DCR that supports both client-side and server-side tests with the same API. It's currently in it's beta/testing phase, so please get in touch with the commercial-dev team if you'd like to use it. [Details on how to use the new framework are at the bottom of this document](#beta-ab-test-framework).
866

877
## Client-side A/B tests
888

@@ -157,3 +77,84 @@ You can verify that you have been correctly assigned to the variant by appending
15777
```
15878

15979
You can access server-side `abTests` within DCR wherever the CAPI object is used (`CAPIArticle.config.abTests`).
80+
81+
# Beta AB Test framework
82+
83+
This is a new framework that has been developed by commercial-dev to support both client and server side A/B tests in DCR. The goal is to eventually replace the legacy A/B testing framework described above with this new framework.
84+
85+
Please get in touch with the commercial-dev team if you'd like up to date information on it's state of readiness.
86+
87+
## Creating a new A/B test
88+
89+
Create an ab test in [ab-testing/abTest.ts](../ab-testing/abTest.ts) both server and client side tests are defined here. More information on defining tests can be found in [ab-testing/README.md](../ab-testing/README.md).
90+
91+
When the config is merged, the A/B test will be automatically deployed and be available at the same time as your changes.
92+
93+
Ab test on/off state is controlled only by the config. Expired tests will cause the ab testing validation to fail, they will also not be served. In effect expired tests are turned off "automatically", but their config needs to be cleaned up.
94+
95+
The test will appear in https://frontend.gutools.co.uk/analytics/ab-testing once the config is deployed.
96+
97+
## Putting code changes behind an A/B test (group)
98+
99+
### Use in Components
100+
101+
Again, this applies to both client and server side tests.
102+
103+
```ts
104+
// Within the components
105+
import { useBetaAB } from '../lib/useAB';
106+
107+
const someComponent = () => {
108+
// Example usage of AB Tests
109+
const abTests = useBetaAB();
110+
111+
// Am I in the test at all?
112+
const isInTest = abTests?.isUserInTest('AbTestTest') ?? false;
113+
114+
const isInControlGroup =
115+
(abTests?.isUserInTestGroup('AbTestTest', 'control') ?? false);
116+
117+
const isInVariantGroup =
118+
abTests?.isUserInTestGroup('AbTestTest', 'variant') ?? false;
119+
120+
if (isInControlGroup) {
121+
return (
122+
<div>
123+
You're in the control group
124+
</div>
125+
);
126+
} else if (isInVariantGroup) {
127+
return (
128+
<div>
129+
You're in the variant group
130+
</div>
131+
);
132+
} else {
133+
return (
134+
<div>
135+
You're not in the test
136+
</div>
137+
);
138+
}
139+
}
140+
141+
```
142+
143+
### Other ways to check
144+
145+
The ab test API is also available on the window object as `window.guardian.modules.abTests`, this only works client side. It's best to use the `useBetaAB` hook in react components.
146+
147+
Server side tests are also available in the CAPI object e.g. `CAPIArticle.config.serverSideABTests`.
148+
149+
## Forcing yourself into a test
150+
151+
Use the opt-in and opt-out URL fragments to force yourself into or out of a test.
152+
153+
When opted-in, the test will override any mvt based assignment and you'll only be in the opted-in test group.
154+
155+
When opted-out, you'll return to random/mvt based assignment.
156+
157+
These links are also in the [frontend admin](https://frontend.gutools.co.uk/analytics/ab-testing).
158+
159+
- Opt-in Example: `https://theguardian.com/ab-tests/opt/in/commercial-test-example:variant`
160+
- Opt-out: `https://theguardian.com/ab-tests/opt/out`

0 commit comments

Comments
 (0)