govuk_ab_testing 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: deb02ae4e64ef50d8e25636153612fafff21d485
-  data.tar.gz: a9ffba9a8db8a463a011cd342616ed452b46ab7f
+  metadata.gz: 33722ac9662c30de4c5efa423f8de33da6341a78
+  data.tar.gz: 0c65ef65524a43ee0108e33c2be4599d83550386
 SHA512:
-  metadata.gz: d9ce66cf58ec982769c9061ec3f20e62ed7e2789408ae88e409b584f72df46a5580835a30db44c3078c47fe291c0a4136826404506bb9a92884307b2f454c20b
-  data.tar.gz: 74c8fc5a0d34a5a11630414ad828c47de97613c5c29768b22a5d4c8f7cb392899a2b79144a47dd97fdcfbee5407b83d4d8d98ed5102c98d2345b3ef9e1b6367d
+  metadata.gz: 0b89a6c500a941ec1ff9c099c96be9663b0628bb8df81ef74a107ae561300ba16750047587d1287cf02f0cca78b9a600f475ff2ffcf08b2eaeb79e02d19ac161
+  data.tar.gz: 7ef09915ff51828ad9843a44a8c2f01cb196d5edafe7fb4dcf4e5e86c29a86b09dfb80efdbbb616c7c10305c36cd7729ef748ba162f743fe3974c3f4d9325f2a

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.4.0
+
+* Add two new optional parameters to `GovukAbTesting::AbTest`:
+  `allowed_variants` and `control_variant`. These allow us to override the
+  traditional naming of the A/B tests and also setup a multivariate test if
+  needed.
+* Add new method to `RequestedVariant` to query if a user is in a given variant.
+  The method is `variant?(name)`, where `name` is the name of the variant.
+  This new method allows for generic variant names, which are useful when
+  reusing A/B testing cookies/headers. If the cookie name and header name are
+  generic, the variant value should provide details on what test is running.
+* Add deprecation warnings to `variant_a?` and `variant_b?`, as they will be
+  replaced by the method `variant?(name)`.
+
 ## 2.3.1
 
 * Fix bug in order to allow us to set multiple headers (i.e. A/B tests) in a

data/README.md

@@ -18,12 +18,9 @@ And then execute:
 
 ### Usage
 
-Before starting this, you'll need to
+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.
+- [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)
 
 To enable testing in the app, your Rails app needs:
@@ -57,7 +54,7 @@ class PartyController < ApplicationController
     @requested_variant = ab_test.requested_variant(request.headers)
     @requested_variant.configure_response(response)
 
-    if @requested_variant.variant_b?
+    if @requested_variant.variant?('B')
       render "new_show_template_to_be_tested"
     else
       render "show"

data/lib/govuk_ab_testing/ab_test.rb

@@ -2,15 +2,22 @@ module GovukAbTesting
   class AbTest
     attr_reader :ab_test_name
     attr_reader :dimension
+    attr_reader :allowed_variants
+    attr_reader :control_variant
 
     alias_method :name, :ab_test_name
 
     # @param request [String] the name of the A/B test
     # @param dimension [Integer] the dimension registered with Google Analytics
     # for this specific A/B test
-    def initialize(ab_test_name, dimension:)
+    # @param allowed_variants [Array] an array of Strings representing the
+    # possible variants
+    # @param control_variant [String] the control variant (typically 'A')
+    def initialize(ab_test_name, dimension:, allowed_variants: %w(A B), control_variant: 'A')
       @ab_test_name = ab_test_name
       @dimension = dimension
+      @allowed_variants = allowed_variants
+      @control_variant = control_variant
     end
 
     # @param request [ActionDispatch::Http::Headers] the `request.headers` in

data/lib/govuk_ab_testing/requested_variant.rb

@@ -17,19 +17,41 @@ module GovukAbTesting
     #
     # @return [String] the current variant, "A" or "B"
     def variant_name
-      request_headers[ab_test.request_header] == "B" ? "B" : "A"
+      variant = ab_test.allowed_variants.find do |allowed_variant|
+        allowed_variant == request_headers[ab_test.request_header]
+      end
+
+      variant || ab_test.control_variant
     end
 
     # @return [Boolean] if the user is to be served variant A
     def variant_a?
+      warn 'DEPRECATION WARNING: the method `variant_a?` is deprecated. use `variant?("A")` instead'
+
       variant_name == "A"
     end
 
     # @return [Boolean] if the user is to be served variant B
     def variant_b?
+      warn 'DEPRECATION WARNING: the method `variant_b?` is deprecated. use `variant?("B")` instead'
+
       variant_name == "B"
     end
 
+    # Check if the user should be served a specific variant
+    #
+    # @param [String or Symbol] the name of the variant
+    #
+    # @return [Boolean] if the user is to be served variant :name
+    def variant?(name)
+      error_message =
+        "Invalid variant name '#{name}'. Allowed variants are: #{ab_test.allowed_variants}"
+
+      raise error_message unless ab_test.allowed_variants.include?(name.to_s)
+
+      variant_name == name.to_s
+    end
+
     # Configure the response
     #
     # @param [ApplicationController::Response] the `response` in the controller
@@ -43,7 +65,8 @@ module GovukAbTesting
     def analytics_meta_tag
       '<meta name="govuk:ab-test" ' +
         'content="' + ab_test.meta_tag_name + ':' + variant_name + '" ' +
-        'data-analytics-dimension="' + @dimension.to_s + '">'
+        'data-analytics-dimension="' + @dimension.to_s + '" ' +
+        'data-allowed-variants="' + ab_test.allowed_variants.join(',') + '">'
     end
   end
 end

data/lib/govuk_ab_testing/version.rb

@@ -1,3 +1,3 @@
 module GovukAbTesting
-  VERSION = "2.3.1".freeze
+  VERSION = "2.4.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_ab_testing
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-07 00:00:00.000000000 Z
+date: 2017-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake