API Docs for: 3.8.0
Show:

File: test/js/ArrayAssert.js


  2. /**
  3.  * The ArrayAssert object provides functions to test JavaScript array objects
  4.  * for a variety of cases.
  5.  * @namespace Test
  6.  * @module test
  7.  * @class ArrayAssert
  8.  * @static
  9.  */
  10.  
  11. YUITest.ArrayAssert = {

  13.     //=========================================================================
  14.     // Private methods
  15.     //=========================================================================
  16.     
  17.     /**
  18.      * Simple indexOf() implementation for an array. Defers to native
  19.      * if available.
  20.      * @param {Array} haystack The array to search.
  21.      * @param {Variant} needle The value to locate.
  22.      * @return {int} The index of the needle if found or -1 if not.
  23.      * @method _indexOf
  24.      * @private
  25.      */
  26.     _indexOf: function(haystack, needle){
  27.         if (haystack.indexOf){
  28.             return haystack.indexOf(needle);
  29.         } else {
  30.             for (var i=0; i < haystack.length; i++){
  31.                 if (haystack[i] === needle){
  32.                     return i;
  33.                 }
  34.             }
  35.             return -1;
  36.         }
  37.     },
  38.     
  39.     /**
  40.      * Simple some() implementation for an array. Defers to native
  41.      * if available.
  42.      * @param {Array} haystack The array to search.
  43.      * @param {Function} matcher The function to run on each value.
  44.      * @return {Boolean} True if any value, when run through the matcher,
  45.      *      returns true.
  46.      * @method _some
  47.      * @private
  48.      */
  49.     _some: function(haystack, matcher){
  50.         if (haystack.some){
  51.             return haystack.some(matcher);
  52.         } else {
  53.             for (var i=0; i < haystack.length; i++){
  54.                 if (matcher(haystack[i])){
  55.                     return true;
  56.                 }
  57.             }
  58.             return false;
  59.         }
  60.     },    

  62.     /**
  63.      * Asserts that a value is present in an array. This uses the triple equals 
  64.      * sign so no type coercion may occur.
  65.      * @param {Object} needle The value that is expected in the array.
  66.      * @param {Array} haystack An array of values.
  67.      * @param {String} message (Optional) The message to display if the assertion fails.
  68.      * @method contains
  69.      * @static
  70.      */
  71.     contains : function (needle, haystack, 
  72.                            message) {
  73.         
  74.         YUITest.Assert._increment();               

  76.         if (this._indexOf(haystack, needle) == -1){
  77.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value " + needle + " (" + (typeof needle) + ") not found in array [" + haystack + "]."));
  78.         }
  79.     },

  81.     /**
  82.      * Asserts that a set of values are present in an array. This uses the triple equals 
  83.      * sign so no type coercion may occur. For this assertion to pass, all values must
  84.      * be found.
  85.      * @param {Object[]} needles An array of values that are expected in the array.
  86.      * @param {Array} haystack An array of values to check.
  87.      * @param {String} message (Optional) The message to display if the assertion fails.
  88.      * @method containsItems
  89.      * @static
  90.      */
  91.     containsItems : function (needles, haystack, 
  92.                            message) {
  93.         YUITest.Assert._increment();               

  95.         //begin checking values
  96.         for (var i=0; i < needles.length; i++){
  97.             if (this._indexOf(haystack, needles[i]) == -1){
  98.                 YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value " + needles[i] + " (" + (typeof needles[i]) + ") not found in array [" + haystack + "]."));
  99.             }
  100.         }
  101.     },

  103.     /**
  104.      * Asserts that a value matching some condition is present in an array. This uses
  105.      * a function to determine a match.
  106.      * @param {Function} matcher A function that returns true if the items matches or false if not.
  107.      * @param {Array} haystack An array of values.
  108.      * @param {String} message (Optional) The message to display if the assertion fails.
  109.      * @method containsMatch
  110.      * @static
  111.      */
  112.     containsMatch : function (matcher, haystack, 
  113.                            message) {
  114.         
  115.         YUITest.Assert._increment();               
  116.         //check for valid matcher
  117.         if (typeof matcher != "function"){
  118.             throw new TypeError("ArrayAssert.containsMatch(): First argument must be a function.");
  119.         }
  120.         
  121.         if (!this._some(haystack, matcher)){
  122.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "No match found in array [" + haystack + "]."));
  123.         }
  124.     },

  126.     /**
  127.      * Asserts that a value is not present in an array. This uses the triple equals 
  128.      * Asserts that a value is not present in an array. This uses the triple equals 
  129.      * sign so no type coercion may occur.
  130.      * @param {Object} needle The value that is expected in the array.
  131.      * @param {Array} haystack An array of values.
  132.      * @param {String} message (Optional) The message to display if the assertion fails.
  133.      * @method doesNotContain
  134.      * @static
  135.      */
  136.     doesNotContain : function (needle, haystack, 
  137.                            message) {
  138.         
  139.         YUITest.Assert._increment();               

  141.         if (this._indexOf(haystack, needle) > -1){
  142.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value found in array [" + haystack + "]."));
  143.         }
  144.     },

  146.     /**
  147.      * Asserts that a set of values are not present in an array. This uses the triple equals 
  148.      * sign so no type coercion may occur. For this assertion to pass, all values must
  149.      * not be found.
  150.      * @param {Object[]} needles An array of values that are not expected in the array.
  151.      * @param {Array} haystack An array of values to check.
  152.      * @param {String} message (Optional) The message to display if the assertion fails.
  153.      * @method doesNotContainItems
  154.      * @static
  155.      */
  156.     doesNotContainItems : function (needles, haystack, 
  157.                            message) {

  159.         YUITest.Assert._increment();               

  161.         for (var i=0; i < needles.length; i++){
  162.             if (this._indexOf(haystack, needles[i]) > -1){
  163.                 YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value found in array [" + haystack + "]."));
  164.             }
  165.         }

  167.     },
  168.         
  169.     /**
  170.      * Asserts that no values matching a condition are present in an array. This uses
  171.      * a function to determine a match.
  172.      * @param {Function} matcher A function that returns true if the item matches or false if not.
  173.      * @param {Array} haystack An array of values.
  174.      * @param {String} message (Optional) The message to display if the assertion fails.
  175.      * @method doesNotContainMatch
  176.      * @static
  177.      */
  178.     doesNotContainMatch : function (matcher, haystack, 
  179.                            message) {
  180.         
  181.         YUITest.Assert._increment();     
  182.       
  183.         //check for valid matcher
  184.         if (typeof matcher != "function"){
  185.             throw new TypeError("ArrayAssert.doesNotContainMatch(): First argument must be a function.");
  186.         }
  187.         
  188.         if (this._some(haystack, matcher)){
  189.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value found in array [" + haystack + "]."));
  190.         }
  191.     },
  192.         
  193.     /**
  194.      * Asserts that the given value is contained in an array at the specified index.
  195.      * This uses the triple equals sign so no type coercion will occur.
  196.      * @param {Object} needle The value to look for.
  197.      * @param {Array} haystack The array to search in.
  198.      * @param {int} index The index at which the value should exist.
  199.      * @param {String} message (Optional) The message to display if the assertion fails.
  200.      * @method indexOf
  201.      * @static
  202.      */
  203.     indexOf : function (needle, haystack, index, message) {
  204.     
  205.         YUITest.Assert._increment();     

  207.         //try to find the value in the array
  208.         for (var i=0; i < haystack.length; i++){
  209.             if (haystack[i] === needle){
  210.                 if (index != i){
  211.                     YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value exists at index " + i + " but should be at index " + index + "."));                    
  212.                 }
  213.                 return;
  214.             }
  215.         }
  216.         
  217.         //if it makes it here, it wasn't found at all
  218.         YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value doesn't exist in array [" + haystack + "]."));
  219.     },
  220.         
  221.     /**
  222.      * Asserts that the values in an array are equal, and in the same position,
  223.      * as values in another array. This uses the double equals sign
  224.      * so type coercion may occur. Note that the array objects themselves
  225.      * need not be the same for this test to pass.
  226.      * @param {Array} expected An array of the expected values.
  227.      * @param {Array} actual Any array of the actual values.
  228.      * @param {String} message (Optional) The message to display if the assertion fails.
  229.      * @method itemsAreEqual
  230.      * @static
  231.      */
  232.     itemsAreEqual : function (expected, actual, 
  233.                            message) {
  234.         
  235.         YUITest.Assert._increment();     
  236.         
  237.         //first make sure they're array-like (this can probably be improved)
  238.         if (typeof expected != "object" || typeof actual != "object"){
  239.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value should be an array."));
  240.         }
  241.         
  242.         //next check array length
  243.         if (expected.length != actual.length){
  244.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Array should have a length of " + expected.length + " but has a length of " + actual.length + "."));
  245.         }
  246.        
  247.         //begin checking values
  248.         for (var i=0; i < expected.length; i++){
  249.             if (expected[i] != actual[i]){
  250.                 throw new YUITest.ComparisonFailure(YUITest.Assert._formatMessage(message, "Values in position " + i + " are not equal."), expected[i], actual[i]);
  251.             }
  252.         }
  253.     },
  254.     
  255.     /**
  256.      * Asserts that the values in an array are equivalent, and in the same position,
  257.      * as values in another array. This uses a function to determine if the values
  258.      * are equivalent. Note that the array objects themselves
  259.      * need not be the same for this test to pass.
  260.      * @param {Array} expected An array of the expected values.
  261.      * @param {Array} actual Any array of the actual values.
  262.      * @param {Function} comparator A function that returns true if the values are equivalent
  263.      *      or false if not.
  264.      * @param {String} message (Optional) The message to display if the assertion fails.
  265.      * @return {Void}
  266.      * @method itemsAreEquivalent
  267.      * @static
  268.      */
  269.     itemsAreEquivalent : function (expected, actual, 
  270.                            comparator, message) {
  271.         
  272.         YUITest.Assert._increment();     

  274.         //make sure the comparator is valid
  275.         if (typeof comparator != "function"){
  276.             throw new TypeError("ArrayAssert.itemsAreEquivalent(): Third argument must be a function.");
  277.         }
  278.         
  279.         //first check array length
  280.         if (expected.length != actual.length){
  281.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Array should have a length of " + expected.length + " but has a length of " + actual.length));
  282.         }
  283.         
  284.         //begin checking values
  285.         for (var i=0; i < expected.length; i++){
  286.             if (!comparator(expected[i], actual[i])){
  287.                 throw new YUITest.ComparisonFailure(YUITest.Assert._formatMessage(message, "Values in position " + i + " are not equivalent."), expected[i], actual[i]);
  288.             }
  289.         }
  290.     },
  291.     
  292.     /**
  293.      * Asserts that an array is empty.
  294.      * @param {Array} actual The array to test.
  295.      * @param {String} message (Optional) The message to display if the assertion fails.
  296.      * @method isEmpty
  297.      * @static
  298.      */
  299.     isEmpty : function (actual, message) {        
  300.         YUITest.Assert._increment();     
  301.         if (actual.length > 0){
  302.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Array should be empty."));
  303.         }
  304.     },    
  305.     
  306.     /**
  307.      * Asserts that an array is not empty.
  308.      * @param {Array} actual The array to test.
  309.      * @param {String} message (Optional) The message to display if the assertion fails.
  310.      * @method isNotEmpty
  311.      * @static
  312.      */
  313.     isNotEmpty : function (actual, message) {        
  314.         YUITest.Assert._increment();     
  315.         if (actual.length === 0){
  316.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Array should not be empty."));
  317.         }
  318.     },    
  319.     
  320.     /**
  321.      * Asserts that the values in an array are the same, and in the same position,
  322.      * as values in another array. This uses the triple equals sign
  323.      * so no type coercion will occur. Note that the array objects themselves
  324.      * need not be the same for this test to pass.
  325.      * @param {Array} expected An array of the expected values.
  326.      * @param {Array} actual Any array of the actual values.
  327.      * @param {String} message (Optional) The message to display if the assertion fails.
  328.      * @method itemsAreSame
  329.      * @static
  330.      */
  331.     itemsAreSame : function (expected, actual, 
  332.                           message) {
  333.         
  334.         YUITest.Assert._increment();     

  336.         //first check array length
  337.         if (expected.length != actual.length){
  338.             YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Array should have a length of " + expected.length + " but has a length of " + actual.length));
  339.         }
  340.                     
  341.         //begin checking values
  342.         for (var i=0; i < expected.length; i++){
  343.             if (expected[i] !== actual[i]){
  344.                 throw new YUITest.ComparisonFailure(YUITest.Assert._formatMessage(message, "Values in position " + i + " are not the same."), expected[i], actual[i]);
  345.             }
  346.         }
  347.     },
  348.     
  349.     /**
  350.      * Asserts that the given value is contained in an array at the specified index,
  351.      * starting from the back of the array.
  352.      * This uses the triple equals sign so no type coercion will occur.
  353.      * @param {Object} needle The value to look for.
  354.      * @param {Array} haystack The array to search in.
  355.      * @param {int} index The index at which the value should exist.
  356.      * @param {String} message (Optional) The message to display if the assertion fails.
  357.      * @method lastIndexOf
  358.      * @static
  359.      */
  360.     lastIndexOf : function (needle, haystack, index, message) {
  361.     
  362.         //try to find the value in the array
  363.         for (var i=haystack.length; i >= 0; i--){
  364.             if (haystack[i] === needle){
  365.                 if (index != i){
  366.                     YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value exists at index " + i + " but should be at index " + index + "."));                    
  367.                 }
  368.                 return;
  369.             }
  370.         }
  371.         
  372.         //if it makes it here, it wasn't found at all
  373.         YUITest.Assert.fail(YUITest.Assert._formatMessage(message, "Value doesn't exist in array."));        
  374.     }
  375.     
  376. };

  378.