govuk_ab_testing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a131dac8f3c6fe3c8bd613056c2c639790807519
+  data.tar.gz: 247f153ccd3d578a4340594198858c34faec0bbb
+SHA512:
+  metadata.gz: da4a7338ea7be7c6535637bf7f8f0d9ab7e047bdd9a55786a6c7d90e2f7e00d7f907c2179ef2e25e85a914945f487054244eb470817c80c4ae0f3ba68af3a9ae
+  data.tar.gz: 074fdfce8d5d4a9dc749fae59c495cfb3a57d5f97561939b5704e1f62ca7bc90e80fb3360ec2bddb61f30335a566c6700d0a937ecf6b8b0a8321b42570a17fec

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in govuk_ab_testing.gemspec
+gemspec

data/Jenkinsfile

@@ -0,0 +1,44 @@
+#!/usr/bin/env groovy
+
+node {
+  def govuk = load '/var/lib/jenkins/groovy_scripts/govuk_jenkinslib.groovy'
+
+  try {
+    stage('Checkout') {
+      checkout scm
+    }
+
+    stage('Clean') {
+      govuk.cleanupGit()
+      govuk.mergeMasterBranch()
+    }
+
+    stage('Bundle') {
+      echo 'Bundling'
+      sh("bundle install --path ${JENKINS_HOME}/bundles/${JOB_NAME}")
+    }
+
+    stage('Linter') {
+      govuk.rubyLinter()
+    }
+
+    stage('Tests') {
+      govuk.setEnvar('RAILS_ENV', 'test')
+      govuk.runTests()
+    }
+
+    if(env.BRANCH_NAME == "master") {
+      stage('Publish Gem') {
+        govuk.runRakeTask("publish_gem --trace")
+      }
+    }
+
+  } catch (e) {
+    currentBuild.result = 'FAILED'
+    step([$class: 'Mailer',
+          notifyEveryUnstableBuild: true,
+          recipients: 'govuk-ci-notifications@digital.cabinet-office.gov.uk',
+          sendToIndividuals: true])
+    throw e
+  }
+}

data/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (C) 2017 Crown copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# GOV.UK A/B Testing
+
+Gem to help with A/B testing on the GOV.UK platform.
+
+## Technical documentation
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'govuk_ab_testing', '~> VERSION'
+```
+
+And then execute:
+
+    $ bundle
+
+### Usage
+
+Before starting this, you'll need to
+
+- get your cookie listed on [/help/cookies](https://www.gov.uk/help/cookies)
+- configure the CDN [like we did for the Education Navigation test](https://github.com/alphagov/govuk-cdn-config/pull/17).
+The cookie and header name in the CDN config must match the test name parameter
+that you pass to the Gem. The cookie name is case-sensitive.
+- configure Google Analytics (guidelines to follow)
+
+To enable testing in the app, your Rails app needs:
+
+1. Some piece of logic to be A/B tested
+2. A HTML meta tag that will be used to measure the results
+3. A response HTTP header that tells Fastly you're doing an A/B test
+
+Let's say you have this controller:
+
+```ruby
+# app/controllers/party_controller.rb
+class PartyController < ApplicationController
+  def show
+    ab_test = GovukAbTesting::AbTest.new("your_ab_test_name")
+    @requested_variant = ab_test.requested_variant(request)
+    @requested_variant.configure_response(response)
+
+    if @requested_variant.variant_b?
+      render "new_show_template_to_be_tested"
+    else
+      render "show"
+    end
+  end
+end
+```
+
+Add this to your layouts, so that we have a meta tag that can be picked up
+by the extension and analytics.
+
+```html
+<!-- application.html.erb -->
+<head>
+  <%= @requested_variant.analytics_meta_tag.html_safe %>
+</head>
+```
+
+#### Test helpers
+
+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:
+
+```ruby
+# test/controllers/party_controller_test.rb
+class PartyControllerTest < ActionController::TestCase
+  include GovukAbTesting::MinitestHelpers
+
+  should "show the user the B version" do
+    with_variant your_ab_test_name: "B" do
+      get :show
+
+      # Optional assertions about page content of the B variant
+    end
+  end
+end
+```
+
+Pass the `assert_meta_tag: false` option to skip assertions about the `meta`
+tag, for example because the variant returns a redirect response rather than
+returning an HTML page.
+
+```ruby
+# test/controllers/party_controller_test.rb
+class PartyControllerTest < ActionController::TestCase
+  include GovukAbTesting::MinitestHelpers
+
+  should "redirect the user the B version" do
+    with_variant your_ab_test_name: "B", assert_meta_tag: false do
+      get :show
+
+      assert_response 302
+      assert_redirected_to { controller: "other_controller", action: "show" }
+    end
+  end
+end
+```
+
+To test the negative case in which a page is unaffected by the A/B test:
+
+```ruby
+# test/controllers/party_controller_test.rb
+class PartyControllerTest < ActionController::TestCase
+  include GovukAbTesting::MinitestHelpers
+
+  should "show the original " do
+    add_ab_test_header("your_ab_test_name", "B")
+
+    get :show
+
+    assert_unaffected_by_ab_test
+  end
+end
+```
+
+### Running the test suite
+
+`bundle exec rake`
+
+### 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)

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "gem_publisher"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Publish gem to RubyGems"
+task :publish_gem do |_t|
+  published_gem = GemPublisher.publish_if_updated("govuk_ab_testing.gemspec", :rubygems)
+  puts "Published #{published_gem}" if published_gem
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "govuk_ab_testing"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/govuk_ab_testing.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'govuk_ab_testing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "govuk_ab_testing"
+  spec.version       = GovukAbTesting::VERSION
+  spec.authors       = ["GOV.UK Dev"]
+  spec.email         = ["govuk-dev@digital.cabinet-office.gov.uk"]
+
+  spec.summary       = %q{Gem to help with A/B testing on the GOV.UK platform}
+  spec.description   = %q{Gem to help with A/B testing on the GOV.UK platform}
+  spec.homepage      = "https://github.com/alphagov/govuk_ab_testing"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_development_dependency "gem_publisher", "~> 1.5.0"
+end

data/lib/govuk_ab_testing/ab_test.rb

@@ -0,0 +1,28 @@
+module GovukAbTesting
+  class AbTest
+    attr_reader :ab_test_name
+
+    def initialize(ab_test_name)
+      @ab_test_name = ab_test_name
+    end
+
+    # @param request [ApplicationController::Request] the `request` in the
+    # controller.
+    def requested_variant(request)
+      RequestedVariant.new(self, request)
+    end
+
+    # Internal name of the header
+    def request_header
+      "HTTP_GOVUK_ABTEST_#{ab_test_name.upcase}"
+    end
+
+    def response_header
+      "GOVUK-ABTest-#{meta_tag_name}"
+    end
+
+    def meta_tag_name
+      ab_test_name
+    end
+  end
+end

data/lib/govuk_ab_testing/minitest_helpers.rb

@@ -0,0 +1,41 @@
+module GovukAbTesting
+  module MinitestHelpers
+    def with_variant(args)
+      ab_test_name, variant = args.first
+
+      ab_test = GovukAbTesting::AbTest.new(ab_test_name.to_s)
+
+      @request.headers[ab_test.request_header] = variant
+      requested_variant = ab_test.requested_variant(@request)
+
+      yield
+
+      assert_equal ab_test.response_header, response.headers['Vary'], "You probably forgot to use `configure_response`"
+
+      unless args[:assert_meta_tag] == false
+        assert_meta_tag "govuk:ab-test",
+          ab_test.meta_tag_name + ':' + requested_variant.variant_name,
+          "You probably forgot to add the `analytics_meta_tag`"
+      end
+    end
+
+    def setup_ab_variant(ab_test_name, variant)
+      ab_test = GovukAbTesting::AbTest.new(ab_test_name)
+
+      @request.headers[ab_test.request_header] = variant
+    end
+
+    def assert_unaffected_by_ab_test
+      assert_nil response.headers['Vary'],
+        "`Vary` header is being added to a page which is outside of the A/B test"
+
+      assert_select "meta[name='govuk:ab-test']", false
+    end
+
+  private
+
+    def assert_meta_tag(name, content, message)
+      assert_select "meta[name='#{name}'][content='#{content}']", 1, message
+    end
+  end
+end

data/lib/govuk_ab_testing/requested_variant.rb

@@ -0,0 +1,45 @@
+module GovukAbTesting
+  class RequestedVariant
+    attr_reader :ab_test, :request
+
+    # @param ab_test [AbTest] the A/B test being performed
+    # @param request [ApplicationController::Request] the `request` in the
+    # controller.
+    def initialize(ab_test, request)
+      @ab_test = ab_test
+      @request = request
+    end
+
+    # Get the bucket this user is in
+    #
+    # @return [String] the current variant, "A" or "B"
+    def variant_name
+      request.headers[ab_test.request_header] == "B" ? "B" : "A"
+    end
+
+    # @return [Boolean] if the user is to be served variant A
+    def variant_a?
+      variant_name == "A"
+    end
+
+    # @return [Boolean] if the user is to be served variant B
+    def variant_b?
+      variant_name == "B"
+    end
+
+    # Configure the response
+    #
+    # @param [ApplicationController::Response] the `response` in the controller
+    def configure_response(response)
+      raise "We're trying to set the Vary header, but this would override the current header" if response.headers['Vary']
+      response.headers['Vary'] = ab_test.response_header
+    end
+
+    # HTML meta tag used to track the results of your experiment
+    #
+    # @return [String]
+    def analytics_meta_tag
+      '<meta name="govuk:ab-test" content="' + ab_test.meta_tag_name + ':' + variant_name + '">'
+    end
+  end
+end

data/lib/govuk_ab_testing/version.rb

@@ -0,0 +1,3 @@
+module GovukAbTesting
+  VERSION = "0.1.0"
+end

data/lib/govuk_ab_testing.rb

@@ -0,0 +1,7 @@
+require "govuk_ab_testing/version"
+require "govuk_ab_testing/requested_variant"
+require "govuk_ab_testing/ab_test"
+require "govuk_ab_testing/minitest_helpers"
+
+module GovukAbTesting
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: govuk_ab_testing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GOV.UK Dev
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: gem_publisher
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+description: Gem to help with A/B testing on the GOV.UK platform
+email:
+- govuk-dev@digital.cabinet-office.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- Jenkinsfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- govuk_ab_testing.gemspec
+- lib/govuk_ab_testing.rb
+- lib/govuk_ab_testing/ab_test.rb
+- lib/govuk_ab_testing/minitest_helpers.rb
+- lib/govuk_ab_testing/requested_variant.rb
+- lib/govuk_ab_testing/version.rb
+homepage: https://github.com/alphagov/govuk_ab_testing
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Gem to help with A/B testing on the GOV.UK platform
+test_files: []