Add explicit fail function.

- Adds an expectation failure to the current spec

[finishes #70975468] Fix #563

lib/jasmine-core/jasmine.js

@@ -709,6 +709,22 @@ getJasmineRequireObj().Env = function(j$) {
     this.pending = function() {
       throw j$.Spec.pendingSpecExceptionMessage;
     };
+
+    this.fail = function(error) {
+      var message = 'Failed';
+      if (error) {
+        message += ': ';
+        message += error.message || error;
+      }
+
+      currentSpec.addExpectationResult(false, {
+        matcherName: '',
+        passed: false,
+        expected: '',
+        actual: '',
+        message: message
+      });
+    };
   }
 
   return Env;
@@ -2578,6 +2594,10 @@ getJasmineRequireObj().interface = function(jasmine, env) {
       return env.pending();
     },
 
+    fail: function() {
+      return env.fail.apply(env, arguments);
+    },
+
     spyOn: function(obj, methodName) {
       return env.spyOn(obj, methodName);
     },

spec/core/integration/EnvSpec.js

@@ -101,6 +101,53 @@ describe("Env integration", function() {
     env.execute();
   });
 
+  it('explicitly fails a spec', function(done) {
+    var env = new j$.Env(),
+        specDone = jasmine.createSpy('specDone');
+
+    env.addReporter({
+      specDone: specDone,
+      jasmineDone: function() {
+        expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+          description: 'has a default message',
+          failedExpectations: [jasmine.objectContaining({
+            message: 'Failed'
+          })]
+        }));
+        expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+          description: 'specifies a message',
+          failedExpectations: [jasmine.objectContaining({
+            message: 'Failed: messy message'
+          })]
+        }));
+        expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+          description: 'has a message from an Error',
+          failedExpectations: [jasmine.objectContaining({
+            message: 'Failed: error message'
+          })]
+        }));
+        done();
+      }
+    });
+
+    env.describe('failing', function() {
+      env.it('has a default message', function() {
+        env.fail();
+      });
+
+      env.it('specifies a message', function() {
+        env.fail('messy message');
+      });
+
+      env.it('has a message from an Error', function() {
+        env.fail(new Error('error message'));
+      });
+    });
+
+    env.execute();
+  });
+
+
   it("calls associated befores/specs/afters with the same 'this'", function(done) {
     var env = new j$.Env();
 
@@ -329,6 +376,64 @@ describe("Env integration", function() {
 
       env.execute();
     });
+
+    it('explicitly fails an async spec', function(done) {
+      var env = new j$.Env(),
+      specDone = jasmine.createSpy('specDone');
+
+      env.addReporter({
+        specDone: specDone,
+        specStarted: function() {
+          jasmine.clock().tick(1);
+        },
+        jasmineDone: function() {
+          expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+            description: 'has a default message',
+            failedExpectations: [jasmine.objectContaining({
+              message: 'Failed'
+            })]
+          }));
+          expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+            description: 'specifies a message',
+            failedExpectations: [jasmine.objectContaining({
+              message: 'Failed: messy message'
+            })]
+          }));
+          expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
+            description: 'has a message from an Error',
+            failedExpectations: [jasmine.objectContaining({
+              message: 'Failed: error message'
+            })]
+          }));
+          done();
+        }
+      });
+
+      env.describe('failing', function() {
+        env.it('has a default message', function(innerDone) {
+          setTimeout(function() {
+            env.fail();
+            innerDone();
+          }, 1);
+        });
+
+        env.it('specifies a message', function(innerDone) {
+          setTimeout(function() {
+            env.fail('messy message');
+            innerDone();
+          }, 1);
+        });
+
+        env.it('has a message from an Error', function(innerDone) {
+          setTimeout(function() {
+            env.fail(new Error('error message'));
+            innerDone();
+          }, 1);
+        });
+      });
+
+      env.execute();
+    });
   });
 
   // TODO: something is wrong with this spec

src/core/Env.js

@@ -335,6 +335,22 @@ getJasmineRequireObj().Env = function(j$) {
     this.pending = function() {
       throw j$.Spec.pendingSpecExceptionMessage;
     };
+
+    this.fail = function(error) {
+      var message = 'Failed';
+      if (error) {
+        message += ': ';
+        message += error.message || error;
+      }
+
+      currentSpec.addExpectationResult(false, {
+        matcherName: '',
+        passed: false,
+        expected: '',
+        actual: '',
+        message: message
+      });
+    };
   }
 
   return Env;

src/core/requireInterface.js

@@ -32,6 +32,10 @@ getJasmineRequireObj().interface = function(jasmine, env) {
       return env.pending();
     },
 
+    fail: function() {
+      return env.fail.apply(env, arguments);
+    },
+
     spyOn: function(obj, methodName) {
       return env.spyOn(obj, methodName);
     },