Add firstArg to spy calls and fakes. (#2150)

Add firstCall convenience property to get the first argument of the last call of a fake.

docs/release-source/release/fakes.md

@@ -152,6 +152,22 @@ f.lastCall.callback === cb2;
 // true
 ```
 
+#### `f.firstArg`
+
+This property is a convenient way to get a reference to the first argument passed in the last call to the fake.
+
+```js
+var f = sinon.fake();
+var date1 = new Date();
+var date2 = new Date();
+
+f(date1, 1, 2);
+f(date2, 1, 2);
+
+f.firstArg === date2;
+// true
+```
+
 #### `f.lastArg`
 
 This property is a convenient way to get a reference to the last argument passed in the last call to the fake.

docs/release-source/release/spy-call.md

@@ -121,6 +121,20 @@ spy.lastCall.callback === callback;
 // true
 ```
 
+#### `spyCall.firstArg`
+
+This property is a convenience for the first argument of the call.
+
+```js
+var spy = sinon.spy();
+var date = new Date();
+
+spy(date, 1, 2);
+
+spy.lastCall.firstArg === date;
+// true
+```
+
 #### `spyCall.lastArg`
 
 This property is a convenience for the last argument of the call.

lib/sinon/fake.js

@@ -14,9 +14,16 @@ var uuid = 0;
 function wrapFunc(f) {
     var proxy;
     var fakeInstance = function() {
-        var lastArg = arguments.length > 0 ? arguments[arguments.length - 1] : undefined;
+        var firstArg, lastArg;
+
+        if (arguments.length > 0) {
+            firstArg = arguments[0];
+            lastArg = arguments[arguments.length - 1];
+        }
+
         var callback = lastArg && typeof lastArg === "function" ? lastArg : undefined;
 
+        proxy.firstArg = firstArg;
         proxy.lastArg = lastArg;
         proxy.callback = callback;
 

lib/sinon/proxy-call.js

@@ -233,13 +233,20 @@ function createProxyCall(proxy, thisValue, args, returnValue, exception, id, err
         throw new TypeError("Call id is not a number");
     }
 
+    var firstArg, lastArg;
+
+    if (args.length > 0) {
+        firstArg = args[0];
+        lastArg = args[args.length - 1];
+    }
+
     var proxyCall = Object.create(callProto);
-    var lastArg = (args.length > 0 && args[args.length - 1]) || undefined;
     var callback = lastArg && typeof lastArg === "function" ? lastArg : undefined;
 
     proxyCall.proxy = proxy;
     proxyCall.thisValue = thisValue;
     proxyCall.args = args;
+    proxyCall.firstArg = firstArg;
     proxyCall.lastArg = lastArg;
     proxyCall.callback = callback;
     proxyCall.returnValue = returnValue;

lib/sinon/proxy.js

@@ -148,6 +148,7 @@ var proxyApi = {
         this.thirdCall = null;
         this.lastCall = null;
         this.args = [];
+        this.firstArg = null;
         this.lastArg = null;
         this.returnValues = [];
         this.thisValues = [];
@@ -297,6 +298,7 @@ function wrapFunction(func, originalFunc) {
         calledThrice: false,
         callCount: 0,
         firstCall: null,
+        firstArg: null,
         secondCall: null,
         thirdCall: null,
         lastCall: null,

test/fake-test.js

@@ -134,6 +134,35 @@ describe("fake", function() {
         });
     });
 
+    describe(".firstArg", function() {
+        it("should be the first argument from the last call", function() {
+            var f = fake();
+            f(41, 42, 43);
+            assert.equals(f.firstArg, 41);
+
+            f(44, 45);
+            assert.equals(f.firstArg, 44);
+
+            f(46);
+            assert.equals(f.firstArg, 46);
+
+            f(false, true, 47, "string");
+            assert.equals(f.firstArg, false);
+
+            f("string", false, true, 47);
+            assert.equals(f.firstArg, "string");
+
+            f(47, "string", false, true);
+            assert.equals(f.firstArg, 47);
+
+            f(true, 47, "string", false);
+            assert.equals(f.firstArg, true);
+
+            f();
+            assert.isUndefined(f.firstArg);
+        });
+    });
+
     describe(".lastArg", function() {
         it("should be the last argument from the last call", function() {
             var f = fake();

test/proxy-call-test.js

@@ -552,6 +552,24 @@ describe("sinonSpy.call", function() {
         });
     });
 
+    describe(".firstArg", function() {
+        it("should be the first argument from the call", function() {
+            var spy = sinonSpy();
+
+            spy(41, 42, 43);
+            assert.equals(spy.getCall(0).firstArg, 41);
+
+            spy(44, 45);
+            assert.equals(spy.getCall(1).firstArg, 44);
+
+            spy(46);
+            assert.equals(spy.getCall(2).firstArg, 46);
+
+            spy();
+            assert.equals(spy.getCall(3).firstArg, undefined);
+        });
+    });
+
     describe(".lastArg", function() {
         it("should be the last argument from the call", function() {
             var spy = sinonSpy();