feat (audiences): Audience combinations (#175)

This adds support for audience combinations on experiments. If `experiment.audienceConditions` is present, it will be used as a condition tree where the leaf conditions are audience Ids.

- Condition tree evaluation and custom attribute condition evaluation are split into separate modules. Condition tree evaluation accepts a leaf evaluator function argument.

- The audience evaluator uses the condition tree evaluator on both the experiment audience conditions and the individual audience conditions.

- Project config methods are updated to support audience combinations.

`getExperimentAudienceConditions` returns `audienceConditions` if it exists, otherwise it falls back to `audienceIds`.

- The audience evaluator treats conditions trees and flat lists of audience ids (the old format) the same way, because a flat list of audience ids is a valid condition tree with an implicit OR condition.

Author: mjc1283

packages/optimizely-sdk/lib/core/audience_evaluator/index.js

@@ -13,36 +13,45 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-var conditionEvaluator = require('../condition_evaluator');
+var conditionTreeEvaluator = require('../condition_tree_evaluator');
+var customAttributeConditionEvaluator = require('../custom_attribute_condition_evaluator');
 
 module.exports = {
   /**
    * Determine if the given user attributes satisfy the given audience conditions
-   * @param  {Object[]} audiences            Audiences to match the user attributes against
-   * @param  {Object[]} audiences.conditions Audience conditions to match the user attributes against
-   * @param  {Object}   [userAttributes]     Hash representing user attributes which will be used in
-   *                                         determining if the audience conditions are met. If not
-   *                                         provided, defaults to an empty object.
-   * @return {Boolean}  True if the user attributes match the given audience conditions
+   * @param  {Array|String|null|undefined}  audienceConditions    Audience conditions to match the user attributes against - can be an array
+   *                                                              of audience IDs, a nested array of conditions, or a single leaf condition.
+   *                                                              Examples: ["5", "6"], ["and", ["or", "1", "2"], "3"], "1"
+   * @param  {Object}                       audiencesById         Object providing access to full audience objects for audience IDs
+   *                                                              contained in audienceConditions. Keys should be audience IDs, values
+   *                                                              should be full audience objects with conditions properties
+   * @param  {Object}                       [userAttributes]      User attributes which will be used in determining if audience conditions
+   *                                                              are met. If not provided, defaults to an empty object
+   * @return {Boolean}                                            true if the user attributes match the given audience conditions, false
+   *                                                              otherwise
    */
-  evaluate: function(audiences, userAttributes) {
+  evaluate: function(audienceConditions, audiencesById, userAttributes) {
     // if there are no audiences, return true because that means ALL users are included in the experiment
-    if (!audiences || audiences.length === 0) {
+    if (!audienceConditions || audienceConditions.length === 0) {
       return true;
     }
 
     if (!userAttributes) {
       userAttributes = {};
     }
 
-    for (var i = 0; i < audiences.length; i++) {
-      var audience = audiences[i];
-      var conditions = audience.conditions;
-      if (conditionEvaluator.evaluate(conditions, userAttributes)) {
-        return true;
+    var evaluateConditionWithUserAttributes = function(condition) {
+      return customAttributeConditionEvaluator.evaluate(condition, userAttributes);
+    };
+
+    var evaluateAudience = function(audienceId) {
+      var audience = audiencesById[audienceId];
+      if (audience) {
+        return conditionTreeEvaluator.evaluate(audience.conditions, evaluateConditionWithUserAttributes);
       }
-    }
+      return null;
+    };
 
-    return false;
+    return conditionTreeEvaluator.evaluate(audienceConditions, evaluateAudience) || false;
   },
 };

packages/optimizely-sdk/lib/core/audience_evaluator/index.tests.js

@@ -15,6 +15,10 @@
  */
 var audienceEvaluator = require('./');
 var chai = require('chai');
+var conditionTreeEvaluator = require('../condition_tree_evaluator');
+var customAttributeConditionEvaluator = require('../custom_attribute_condition_evaluator');
+var sinon = require('sinon');
+
 var assert = chai.assert;
 
 var chromeUserAudience = {
@@ -31,16 +35,29 @@ var iphoneUserAudience = {
     type: 'custom_attribute',
   }],
 };
+var conditionsPassingWithNoAttrs = ['not', {
+  match: 'exists',
+  name: 'input_value',
+  type: 'custom_attribute',
+}];
+var conditionsPassingWithNoAttrsAudience = {
+  conditions: conditionsPassingWithNoAttrs,
+};
+var audiencesById = {
+  0: chromeUserAudience,
+  1: iphoneUserAudience,
+  2: conditionsPassingWithNoAttrsAudience,
+};
 
 describe('lib/core/audience_evaluator', function() {
   describe('APIs', function() {
     describe('evaluate', function() {
       it('should return true if there are no audiences', function() {
-        assert.isTrue(audienceEvaluator.evaluate([], {}));
+        assert.isTrue(audienceEvaluator.evaluate([], audiencesById, {}));
       });
 
       it('should return false if there are audiences but no attributes', function() {
-        assert.isFalse(audienceEvaluator.evaluate([chromeUserAudience], {}));
+        assert.isFalse(audienceEvaluator.evaluate(['0'], audiencesById, {}));
       });
 
       it('should return true if any of the audience conditions are met', function() {
@@ -57,9 +74,9 @@ describe('lib/core/audience_evaluator', function() {
           'device_model': 'iphone',
         };
 
-        assert.isTrue(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], iphoneUsers));
-        assert.isTrue(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], chromeUsers));
-        assert.isTrue(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], iphoneChromeUsers));
+        assert.isTrue(audienceEvaluator.evaluate(['0', '1'], audiencesById, iphoneUsers));
+        assert.isTrue(audienceEvaluator.evaluate(['0', '1'], audiencesById, chromeUsers));
+        assert.isTrue(audienceEvaluator.evaluate(['0', '1'], audiencesById, iphoneChromeUsers));
       });
 
       it('should return false if none of the audience conditions are met', function() {
@@ -76,21 +93,98 @@ describe('lib/core/audience_evaluator', function() {
           'device_model': 'nexus5',
         };
 
-        assert.isFalse(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], nexusUsers));
-        assert.isFalse(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], safariUsers));
-        assert.isFalse(audienceEvaluator.evaluate([chromeUserAudience, iphoneUserAudience], nexusSafariUsers));
+        assert.isFalse(audienceEvaluator.evaluate(['0', '1'], audiencesById, nexusUsers));
+        assert.isFalse(audienceEvaluator.evaluate(['0', '1'], audiencesById, safariUsers));
+        assert.isFalse(audienceEvaluator.evaluate(['0', '1'], audiencesById, nexusSafariUsers));
       });
 
       it('should return true if no attributes are passed and the audience conditions evaluate to true in the absence of attributes', function() {
-        var conditionsPassingWithNoAttrs = ['not', {
-          match: 'exists',
-          name: 'input_value',
-          type: 'custom_attribute',
-        }];
-        var audience = {
-          conditions: conditionsPassingWithNoAttrs,
-        };
-        assert.isTrue(audienceEvaluator.evaluate([audience]));
+        assert.isTrue(audienceEvaluator.evaluate(['2'], audiencesById));
+      });
+
+      describe('complex audience conditions', function() {
+        it('should return true if any of the audiences in an "OR" condition pass', function() {
+          var result = audienceEvaluator.evaluate(
+            ['or', '0', '1'],
+            audiencesById,
+            { browser_type: 'chrome' }
+          );
+          assert.isTrue(result);
+        });
+
+        it('should return true if all of the audiences in an "AND" condition pass', function() {
+          var result = audienceEvaluator.evaluate(
+            ['and', '0', '1'],
+            audiencesById,
+            { browser_type: 'chrome', device_model: 'iphone' }
+          );
+          assert.isTrue(result);
+        });
+
+        it('should return true if the audience in a "NOT" condition does not pass', function() {
+          var result = audienceEvaluator.evaluate(
+            ['not', '1'],
+            audiencesById,
+            { device_model: 'android' }
+          );
+          assert.isTrue(result);
+        });
+
+      });
+
+      describe('integration with dependencies', function() {
+        var sandbox = sinon.sandbox.create();
+
+        beforeEach(function() {
+          sandbox.stub(conditionTreeEvaluator, 'evaluate');
+          sandbox.stub(customAttributeConditionEvaluator, 'evaluate');
+        });
+
+        afterEach(function() {
+          sandbox.restore();
+        });
+
+        it('returns true if conditionTreeEvaluator.evaluate returns true', function() {
+          conditionTreeEvaluator.evaluate.returns(true);
+          var result = audienceEvaluator.evaluate(
+            ['or', '0', '1'],
+            audiencesById,
+            { browser_type: 'chrome' }
+          );
+          assert.isTrue(result);
+        });
+
+        it('returns false if conditionTreeEvaluator.evaluate returns false', function() {
+          conditionTreeEvaluator.evaluate.returns(false);
+          var result = audienceEvaluator.evaluate(
+            ['or', '0', '1'],
+            audiencesById,
+            { browser_type: 'safari' }
+          );
+          assert.isFalse(result);
+        });
+
+        it('returns false if conditionTreeEvaluator.evaluate returns null', function() {
+          conditionTreeEvaluator.evaluate.returns(null);
+          var result = audienceEvaluator.evaluate(
+            ['or', '0', '1'],
+            audiencesById,
+            { state: 'California' }
+          );
+          assert.isFalse(result);
+        });
+
+        it('calls customAttributeConditionEvaluator.evaluate in the leaf evaluator for audience conditions', function() {
+          conditionTreeEvaluator.evaluate.callsFake(function(conditions, leafEvaluator) {
+            return leafEvaluator(conditions[1]);
+          });
+          customAttributeConditionEvaluator.evaluate.returns(false);
+          var userAttributes = { device_model: 'android' };
+          var result = audienceEvaluator.evaluate(['or', '1'], audiencesById, userAttributes);
+          sinon.assert.calledOnce(customAttributeConditionEvaluator.evaluate);
+          sinon.assert.calledWithExactly(customAttributeConditionEvaluator.evaluate, iphoneUserAudience.conditions[1], userAttributes);
+          assert.isFalse(result);
+        });
       });
     });
   });