add throwsArg(index) to stubs

docs/_releases/v1.17.6/stubs.md

@@ -219,6 +219,12 @@ Causes the stub to throw an exception of the provided type.
 
 Causes the stub to throw the provided exception object.
 
+#### `stub.throwsArg(index);`
+
+Causes the stub to throw the argument exception at the provided index. Throws a `TypeError` if called with fewer than `index` arguments.
+
+`stub.throwsArg(0);` causes the stub to throw the first argument exception.
+
 
 #### `stub.callsArg(index);`
 

lib/sinon/behavior.js

@@ -113,6 +113,7 @@ var proto = {
                 this.exception ||
                 typeof this.returnArgAt === "number" ||
                 this.returnThis ||
+                typeof this.throwArgAt === "number" ||
                 this.fakeFn ||
                 this.returnValueDefined);
     },
@@ -126,6 +127,15 @@ var proto = {
             return args[this.returnArgAt];
         } else if (this.returnThis) {
             return context;
+        } else if (typeof this.throwArgAt === "number") {
+            if (args.length < this.throwArgAt) {
+                throw new TypeError(
+                    "throwArgs failed: " + this.throwArgAt
+                    + " arguments required but only " + args.length
+                    + " present"
+                );
+            }
+            throw args[this.throwArgAt];
         } else if (this.fakeFn) {
             return this.fakeFn.apply(context, args);
         } else if (this.resolve) {

lib/sinon/call.js

@@ -105,6 +105,18 @@ var callProto = {
         this.args[pos].apply(thisValue, args);
     },
 
+    throwArg: function (pos) {
+        if (pos > this.args.length) {
+            throw new TypeError(
+                "Not enough arguments: " + pos
+                + " required but only " + this.args.length
+                + " present"
+            );
+        }
+
+        throw this.args[pos];
+    },
+
     "yield": function () {
         this.yieldOn.apply(this, [null].concat(slice.call(arguments, 0)));
     },

lib/sinon/default-behaviors.js

@@ -128,6 +128,14 @@ module.exports = {
         fake.returnArgAt = pos;
     },
 
+    throwsArg: function throwsArg(fake, pos) {
+        if (typeof pos !== "number") {
+            throw new TypeError("argument index is not number");
+        }
+
+        fake.throwArgAt = pos;
+    },
+
     returnsThis: function returnsThis(fake) {
         fake.returnThis = true;
     },

lib/sinon/spy.js

@@ -394,6 +394,9 @@ delegateToCalls("callArgOn", false, "callArgOnWith", function () {
     throw new Error(this.toString() + " cannot call arg since it was not yet invoked.");
 });
 spyApi.callArgOnWith = spyApi.callArgOn;
+delegateToCalls("throwArg", false, "throwArg", function () {
+    throw new Error(this.toString() + " cannot throw arg since it was not yet invoked.");
+});
 delegateToCalls("yield", false, "yield", function () {
     throw new Error(this.toString() + " cannot yield since it was not yet invoked.");
 });

lib/sinon/stub.js

@@ -92,6 +92,7 @@ var proto = {
 
         delete this.returnValue;
         delete this.returnArgAt;
+        delete this.throwArgAt;
         delete this.fakeFn;
         this.returnThis = false;
 

test/spy-test.js

@@ -2294,6 +2294,59 @@ describe("spy", function () {
         });
     });
 
+    describe(".throwArg", function () {
+        it("should be a function", function () {
+            var spy = createSpy();
+
+            assert.isFunction(spy.throwArg);
+        });
+
+        it("should throw if spy hasn't been called", function () {
+            var spy = createSpy();
+
+            assert.exception(
+                function () {
+                    spy.throwArg(0);
+                },
+                function (error) {
+                    return error.message === "spy cannot throw arg since it was not yet invoked.";
+                }
+            );
+        });
+
+        it("should throw if there aren't enough arguments in the previous spy call", function () {
+            var spy = createSpy();
+
+            spy("only", "four", "arguments", "here");
+
+            assert.exception(
+                function () {
+                    spy.throwArg(7);
+                },
+                function (error) {
+                    return error.message === "Not enough arguments: 7 required but only 4 present";
+                }
+            );
+        });
+
+        it("should throw specified argument", function () {
+            var spy = createSpy();
+            var expectedError = new TypeError("catpants");
+
+            spy(true, false, null, expectedError, "meh");
+            assert.exception(
+                function () {
+                    spy.throwArg(3);
+                },
+                function (error) {
+                    return error instanceof TypeError
+                        && error.message === expectedError.message
+                    ;
+                }
+            );
+        });
+    });
+
     describe(".reset", function () {
         it("return same object", function () {
             var spy = createSpy();
@@ -2328,3 +2381,4 @@ describe("spy", function () {
         });
     });
 });
+

test/stub-test.js

@@ -279,6 +279,84 @@ describe("stub", function () {
         });
     });
 
+    describe(".throwsArg", function () {
+        it("throws argument at specified index", function () {
+            var stub = createStub.create();
+            stub.throwsArg(0);
+            var expectedError = new Error("The expected error message");
+
+            assert.exception(function () {
+                stub(expectedError);
+            }, function (err) {
+                return err.message === expectedError.message;
+            });
+        });
+
+        it("returns stub", function () {
+            var stub = createStub.create();
+
+            assert.same(stub.throwsArg(0), stub);
+        });
+
+        it("throws TypeError if no index is specified", function () {
+            var stub = createStub.create();
+
+            assert.exception(function () {
+                stub.throwsArg();
+            }, "TypeError");
+        });
+
+        it("should throw without enough arguments", function () {
+            var stub = createStub.create();
+            stub.throwsArg(3);
+
+            assert.exception(
+                function () {
+                    stub("only", "two arguments");
+                },
+                function (error) {
+                    return error instanceof TypeError
+                        && error.message ===
+                        "throwArgs failed: 3 arguments required but only 2 present"
+                    ;
+                }
+            );
+
+        });
+
+        it("should work with call-based behavior", function () {
+            var stub = createStub.create();
+            var expectedError = new Error("catpants");
+
+            stub.returns(1);
+            stub.onSecondCall().throwsArg(1);
+
+            refute.exception(function () {
+                assert.equals(1, stub(null, expectedError));
+            });
+
+            assert.exception(
+                function () {
+                    stub(null, expectedError);
+                },
+                function (error) {
+                    return error.message === expectedError.message;
+                }
+            );
+        });
+
+        it("should be reset by .resetBeahvior", function () {
+            var stub = createStub.create();
+
+            stub.throwsArg(0);
+            stub.resetBehavior();
+
+            refute.exception(function () {
+                stub(new Error("catpants"));
+            });
+        });
+    });
+
     describe(".returnsThis", function () {
         it("stub returns this", function () {
             var instance = {};