README.md in govuk_ab_testing-2.4.2 vs README.md in govuk_ab_testing-2.4.3

- old
+ new

@@ -1,52 +1,42 @@ # GOV.UK A/B Testing Gem to help with A/B testing on the GOV.UK platform. -## Technical documentation +## Installation -### Installation - Add this line to your application's Gemfile: ```ruby gem 'govuk_ab_testing', '~> VERSION' ``` And then execute: $ bundle -### Usage +## Pre-requisites Before starting this, you'll need to: -- [read the documentation](https://docs.publishing.service.gov.uk/manual/ab-testing.html) on how to set up an a/b test. The cookie and header name in [fastly-configure](https://github.com/alphagov/fastly-configure) and [CDN config](https://github.digital.cabinet-office.gov.uk/gds/cdn-configs) must match the test name parameter that you pass to the Gem. The cookie name is case-sensitive. -- configure Google Analytics (guidelines to follow) +- [Read the documentation](https://docs.publishing.service.gov.uk/manual/ab-testing.html) for an overview on how a/b testing works on GOV.UK. +- The cookie and header name in [govuk-cdn-config](https://github.com/alphagov/govuk-cdn-config/blob/master/ab_tests/ab_tests.yaml) must match the test name parameter that you pass to the Gem. The cookie name is case-sensitive. -To enable testing in the app, your Rails app needs: +## Usage -1. Some piece of logic to be A/B tested -2. A HTML meta tag that will be used to measure the results, and which specifies -the dimension to use in Google Analytics -3. A response HTTP header that tells Fastly you're doing an A/B test +### Outline -Start by defining which acceptance testing framework you will use. This gem -supports both Capybara and ActiveSupport. In order to configure it, add this to -your test helper file: +To enable testing in the app, your Rails app needs: -``` -GovukAbTesting.configure do |config| - config.acceptance_test_framework = :capybara # or :active_support -end -``` +1. [Some piece of logic to be A/B tested](#1-example-ab-test-logic) +2. [A response HTTP header that tells Fastly you're doing an A/B test](#2-http-response-header-to-fastly) +3. [A HTML meta tag that will be used to measure the results, and which specifies + the dimension to use in Google Analytics](#3-add-html-metatag-tags-to-your-layouts) -If we use capybara, the gem expects `page` to be defined in the scope of the -test cases. If we use ActiveSupport, the gem expects `@request` to be defined in -the scope of the test cases. +### 1. Example A/B test logic -Now, let's say you have this controller: +Let's say you have this controller: ```ruby # app/controllers/party_controller.rb class PartyController < ApplicationController def show @@ -71,29 +61,99 @@ end ``` In this example, we are running a multivariate test with 3 options being tested: the existing version (control), and two title changes. The minimum -number of variants in any test should be two. +number of variants in any test should be two. -Then, add this to your layouts, so that we have a meta tag that can be picked up -by the extension and analytics. +### 2. HTTP response header to Fastly +The `configure_response` method used in the example in `step 1` sends the response header. The header helps Fastly to understand which variant was returned to the user and cache appropriately. + +### 3. Add HTML metatag tags to your layouts + +This is for the extension and analytics. + ```html <!-- application.html.erb --> <head> <%= @requested_variant.analytics_meta_tag.html_safe %> </head> ``` The analytics meta tag will include the allowed variants so the extension knows -which variants to suggest the user. +which variants to suggest to the user. -#### Test helpers +## Running the test suite for the gem -##### Minitest +`bundle exec rake` +## Acceptance testing + +Start by defining which acceptance testing framework you will use. This gem +supports both Capybara and ActiveSupport. In order to configure it, add this to +your test helper file: + +``` +GovukAbTesting.configure do |config| + config.acceptance_test_framework = :capybara # or :active_support +end +``` + +If we use capybara, the gem expects `page` to be defined in the scope of the +test cases. If we use ActiveSupport, the gem expects `@request` to be defined in +the scope of the test cases. + +### Test helpers + +#### RSpec + +It is also possible to use `with_variant` and all the individual setup and +assertions steps in RSpec tests. Here is an example of a Capybara feature file: + +```ruby +# spec/features/ab_testing_spec.rb +feature "Viewing a page with an A/B test" do + include GovukAbTesting::RspecHelpers + + scenario "viewing the B version of the page" do + with_variant your_ab_test_name: 'B' do + visit root_path + + expect(page).to have_breadcrumbs + expect(page).to have_beta_label + end + end +end +``` + +And here is an RSpec controller test: + +```ruby +# spec/controllers/some_controller_spec.rb +describe SomeController, type :controller do + include GovukAbTesting::RspecHelpers + + # RSpec doesn't render views for controller specs by default + render_views + + it "should render the B version of the page" do + with_variant your_ab_test_name: 'B' do + get :index + end + end +end +``` + +As with the `minitest` version, you can also pass in the following options to +`with_variant`: + +- `assert_meta_tag: false` +- `dimension: <number>` + +#### Minitest + The most common usage of an A/B test is to serve two different variants of the same page. In this situation, you can test the controller using `with_variant`. It will configure the request and assert that the response is configured correctly: @@ -167,73 +227,24 @@ assert_page_not_tracked_in_ab_test("your_ab_test_name") end end ``` -##### RSpec +## API documentation -It is also possible to use `with_variant` and all the individual setup and -assertions steps in RSpec tests. Here is an example of a Capybara feature file: +See [RubyDoc](http://www.rubydoc.info/gems/govuk_ab_testing) for documentation including all of the assertions for tests. -```ruby -# spec/features/ab_testing_spec.rb -feature "Viewing a page with an A/B test" do - include GovukAbTesting::RspecHelpers +To run a Yard server locally to preview documentation, run: - scenario "viewing the B version of the page" do - with_variant your_ab_test_name: 'B' do - visit root_path + $ bundle exec yard server --reload - expect(page).to have_breadcrumbs - expect(page).to have_beta_label - end - end -end -``` +## Checking your A/B test in a browser -And here is an RSpec controller test: - -```ruby -# spec/controllers/some_controller_spec.rb -describe SomeController, type :controller do - include GovukAbTesting::RspecHelpers - - # RSpec doesn't render views for controller specs by default - render_views - - it "should render the B version of the page" do - with_variant your_ab_test_name: 'B' do - get :index - end - end -end -``` - -As with the `minitest` version, you can also pass in the following options to -`with_variant`: - -- `assert_meta_tag: false` -- `dimension: <number>` - -### Running the test suite - -`bundle exec rake` - -### Testing in a browser - If you want to test this behaviour in a browser then you should use the -[GOV.UK Toolkit for Chrome](https://github.com/alphagov/govuk-toolkit-chrome). +[GOV.UK Toolkit browser extension](https://github.com/alphagov/govuk-browser-extension). This detects when you have a test running on a page and enables you to choose between variants. -### Documentation - -See [RubyDoc](http://www.rubydoc.info/gems/govuk_ab_testing) for some limited documentation. - -To run a Yard server locally to preview documentation, run: - - $ bundle exec yard server --reload - ## Licence -[MIT License](LICENCE.txt) +[MIT License](LICENCE)