Breaking change: Made Env#execute async

Errors related to invalid spec order are now reported via promise
rejection rather than synchronous throw.

lib/jasmine-core/jasmine.js

@@ -1651,15 +1651,17 @@ getJasmineRequireObj().Env = function(j$) {
      * {@link JasmineDoneInfo|overall result} that's passed to a reporter's
      * `jasmineDone` method, even if the suite did not pass. To determine
      * whether the suite passed, check the value that the promise resolves to
-     * or use a {@link Reporter}.
+     * or use a {@link Reporter}. The promise will be rejected in the case of
+     * certain serious errors that prevent execution from starting.
      *
      * @name Env#execute
      * @since 2.0.0
      * @function
+     * @async
      * @param {(string[])=} runablesToRun IDs of suites and/or specs to run
      * @return {Promise<JasmineDoneInfo>}
      */
-    this.execute = function(runablesToRun) {
+    this.execute = async function(runablesToRun) {
       installGlobalErrors();
       return runner.execute(runablesToRun);
     };
@@ -8398,11 +8400,7 @@ getJasmineRequireObj().Runner = function(j$) {
       ];
     }
 
-    // Although execute returns a promise, it isn't async for backwards
-    // compatibility: The "Invalid order" exception needs to be propagated
-    // synchronously from Env#execute.
-    // TODO: make this and Env#execute async in the next major release
-    execute(runablesToRun) {
+    async execute(runablesToRun) {
       if (this.executedBefore_) {
         this.topSuite_.reset();
       }

spec/core/integration/SpecRunningSpec.js

@@ -626,7 +626,7 @@ describe('spec running', function() {
     expect(actions).toEqual(['spec2', 'spec3', 'spec1']);
   });
 
-  it('refuses to re-enter suites with a beforeAll', function() {
+  it('refuses to re-enter suites with a beforeAll', async function() {
     const actions = [];
     let spec1;
     let spec2;
@@ -648,13 +648,12 @@ describe('spec running', function() {
       actions.push('spec3');
     });
 
-    expect(function() {
-      env.execute([spec2.id, spec3.id, spec1.id]);
-    }).toThrowError(/beforeAll/);
+    const promise = env.execute([spec2.id, spec3.id, spec1.id]);
+    await expectAsync(promise).toBeRejectedWithError(/beforeAll/);
     expect(actions).toEqual([]);
   });
 
-  it('refuses to re-enter suites with a afterAll', function() {
+  it('refuses to re-enter suites with a afterAll', async function() {
     const actions = [];
     let spec1;
     let spec2;
@@ -676,9 +675,8 @@ describe('spec running', function() {
       actions.push('spec3');
     });
 
-    expect(function() {
-      env.execute([spec2.id, spec3.id, spec1.id]);
-    }).toThrowError(/afterAll/);
+    const promise = env.execute([spec2.id, spec3.id, spec1.id]);
+    await expectAsync(promise).toBeRejectedWithError(/afterAll/);
     expect(actions).toEqual([]);
   });
 

src/core/Env.js

@@ -509,15 +509,17 @@ getJasmineRequireObj().Env = function(j$) {
      * {@link JasmineDoneInfo|overall result} that's passed to a reporter's
      * `jasmineDone` method, even if the suite did not pass. To determine
      * whether the suite passed, check the value that the promise resolves to
-     * or use a {@link Reporter}.
+     * or use a {@link Reporter}. The promise will be rejected in the case of
+     * certain serious errors that prevent execution from starting.
      *
      * @name Env#execute
      * @since 2.0.0
      * @function
+     * @async
      * @param {(string[])=} runablesToRun IDs of suites and/or specs to run
      * @return {Promise<JasmineDoneInfo>}
      */
-    this.execute = function(runablesToRun) {
+    this.execute = async function(runablesToRun) {
       installGlobalErrors();
       return runner.execute(runablesToRun);
     };

src/core/Runner.js

@@ -26,11 +26,7 @@ getJasmineRequireObj().Runner = function(j$) {
       ];
     }
 
-    // Although execute returns a promise, it isn't async for backwards
-    // compatibility: The "Invalid order" exception needs to be propagated
-    // synchronously from Env#execute.
-    // TODO: make this and Env#execute async in the next major release
-    execute(runablesToRun) {
+    async execute(runablesToRun) {
       if (this.executedBefore_) {
         this.topSuite_.reset();
       }