From f39d7509f054aaa9e0ec80b99cad74fca2386cdb Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Fri, 22 Dec 2017 11:12:47 -0800
Subject: [PATCH 01/19] Expect only overrides error stack for built-in matchers

---
 CHANGELOG.md                                  |  4 +--
 .../expect/src/__tests__/stacktrace.test.js   | 32 +++++++++++++++++--
 packages/expect/src/index.js                  | 14 +++++---
 packages/expect/src/jest_matchers_object.js   |  9 +++++-
 types/Matchers.js                             |  1 +
 5 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8caaba089165..c23dbcd64c97 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,11 +1,11 @@
 ## master
 
-None for now
-
 ### Fixes
 
 * `[babel-jest]` moduleFileExtensions not passed to babel transformer.
   ([#4637](https://github.com/facebook/jest/issues/4637))
+* Do not override `Error` stack (with `Error.captureStackTrace`) for custom matchers.
+  ([#5162](https://github.com/facebook/jest/pull/5162))
 
 ### Features
 
diff --git a/packages/expect/src/__tests__/stacktrace.test.js b/packages/expect/src/__tests__/stacktrace.test.js
index 0d054206cc60..8c7eeaf5e0fa 100644
--- a/packages/expect/src/__tests__/stacktrace.test.js
+++ b/packages/expect/src/__tests__/stacktrace.test.js
@@ -16,13 +16,25 @@ jestExpect.extend({
       pass: true,
     };
   },
+  toCustomMatch(callback, expectation) {
+    const actual = callback();
+
+    if (actual !== expectation) {
+      return {
+        pass: false,
+        message: () => `Expected "${expectation}" but got "${actual}"`
+      };
+    }
+
+    return {pass: true};
+  },
 });
 
 it('stack trace points to correct location when using matchers', () => {
   try {
     jestExpect(true).toBe(false);
   } catch (error) {
-    expect(error.stack).toContain('stacktrace.test.js:23');
+    expect(error.stack).toContain('stacktrace.test.js:35');
   }
 });
 
@@ -32,6 +44,22 @@ it('stack trace points to correct location when using nested matchers', () => {
       jestExpect(value).toBe(false);
     });
   } catch (error) {
-    expect(error.stack).toContain('stacktrace.test.js:32');
+    expect(error.stack).toContain('stacktrace.test.js:44');
+  }
+});
+
+it('stack trace points to correct location when throwing from a custom matcher', () => {
+  try {
+    jestExpect(() => {
+      const foo = () => bar();
+      const bar = () => baz();
+      const baz = () => {
+        throw new Error('Expected');
+      };
+
+      foo();
+    }).toCustomMatch('bar');
+  } catch (error) {
+    expect(error.stack).toContain('stacktrace.test.js:57');
   }
 });
diff --git a/packages/expect/src/index.js b/packages/expect/src/index.js
index 832eca8d4e52..b8fc57d237d5 100644
--- a/packages/expect/src/index.js
+++ b/packages/expect/src/index.js
@@ -214,6 +214,7 @@ const makeThrowingMatcher = (
       result = matcher.apply(matcherContext, [actual].concat(args));
     } catch (error) {
       if (
+        matcher.__jestInternal === true &&
         !(error instanceof JestAssertionError) &&
         error.name !== 'PrettyFormatPluginError' &&
         // Guard for some environments (browsers) that do not support this feature.
@@ -252,7 +253,8 @@ const makeThrowingMatcher = (
   };
 };
 
-expect.extend = (matchers: MatchersObject): void => setMatchers(matchers);
+expect.extend = (matchers: MatchersObject): void =>
+  setMatchers(matchers, false);
 
 expect.anything = anything;
 expect.any = any;
@@ -280,9 +282,9 @@ const _validateResult = result => {
 };
 
 // add default jest matchers
-expect.extend(matchers);
-expect.extend(spyMatchers);
-expect.extend(toThrowMatchers);
+setMatchers(matchers, true);
+setMatchers(spyMatchers, true);
+setMatchers(toThrowMatchers, true);
 
 expect.addSnapshotSerializer = () => void 0;
 expect.assertions = (expected: number) => {
@@ -296,4 +298,8 @@ expect.getState = getState;
 expect.setState = setState;
 expect.extractExpectedAssertionsErrors = extractExpectedAssertionsErrors;
 
+// Expose JestAssertionError for custom matchers
+// This enables them to preserve the stack for specific errors
+expect.JestAssertionError = JestAssertionError;
+
 module.exports = (expect: Expect);
diff --git a/packages/expect/src/jest_matchers_object.js b/packages/expect/src/jest_matchers_object.js
index 14dc7d1e1696..f53e5687c345 100644
--- a/packages/expect/src/jest_matchers_object.js
+++ b/packages/expect/src/jest_matchers_object.js
@@ -35,6 +35,13 @@ export const setState = (state: Object) => {
 
 export const getMatchers = () => global[JEST_MATCHERS_OBJECT].matchers;
 
-export const setMatchers = (matchers: MatchersObject) => {
+export const setMatchers = (matchers: MatchersObject, isInternal: boolean) => {
+  for (const key in matchers) {
+    const matcher = matchers[key];
+    Object.defineProperty(matcher, '__jestInternal', {
+      value: isInternal,
+    });
+  }
+
   Object.assign(global[JEST_MATCHERS_OBJECT].matchers, matchers);
 };
diff --git a/types/Matchers.js b/types/Matchers.js
index 04e11e5b0939..b4824891e56f 100644
--- a/types/Matchers.js
+++ b/types/Matchers.js
@@ -19,6 +19,7 @@ export type RawMatcherFn = (
   expected: any,
   actual: any,
   options: any,
+  __jestInternal?: boolean,
 ) => ExpectationResult;
 
 export type ThrowingMatcherFn = (actual: any) => void;

From e7d9bbd6b87e1128f860d582cb90e827aa0d7268 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Fri, 22 Dec 2017 13:01:24 -0800
Subject: [PATCH 02/19] Fixed naggy lint issue

---
 packages/expect/src/__tests__/stacktrace.test.js | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/expect/src/__tests__/stacktrace.test.js b/packages/expect/src/__tests__/stacktrace.test.js
index 8c7eeaf5e0fa..1c60ddbd40d8 100644
--- a/packages/expect/src/__tests__/stacktrace.test.js
+++ b/packages/expect/src/__tests__/stacktrace.test.js
@@ -9,25 +9,25 @@
 const jestExpect = require('../');
 
 jestExpect.extend({
-  toMatchPredicate(received, argument) {
-    argument(received);
-    return {
-      message: () => '',
-      pass: true,
-    };
-  },
   toCustomMatch(callback, expectation) {
     const actual = callback();
 
     if (actual !== expectation) {
       return {
+        message: () => `Expected "${expectation}" but got "${actual}"`,
         pass: false,
-        message: () => `Expected "${expectation}" but got "${actual}"`
       };
     }
 
     return {pass: true};
   },
+  toMatchPredicate(received, argument) {
+    argument(received);
+    return {
+      message: () => '',
+      pass: true,
+    };
+  },
 });
 
 it('stack trace points to correct location when using matchers', () => {

From 9c10921e98cfca6ed7e426bbf94806ded02da88f Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Fri, 22 Dec 2017 13:01:38 -0800
Subject: [PATCH 03/19] Replaced for...of with Object.keys().forEach()

---
 packages/expect/src/jest_matchers_object.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/expect/src/jest_matchers_object.js b/packages/expect/src/jest_matchers_object.js
index f53e5687c345..fb7ca10d23c6 100644
--- a/packages/expect/src/jest_matchers_object.js
+++ b/packages/expect/src/jest_matchers_object.js
@@ -36,12 +36,12 @@ export const setState = (state: Object) => {
 export const getMatchers = () => global[JEST_MATCHERS_OBJECT].matchers;
 
 export const setMatchers = (matchers: MatchersObject, isInternal: boolean) => {
-  for (const key in matchers) {
+  Object.keys(matchers).forEach(key => {
     const matcher = matchers[key];
     Object.defineProperty(matcher, '__jestInternal', {
       value: isInternal,
     });
-  }
+  });
 
   Object.assign(global[JEST_MATCHERS_OBJECT].matchers, matchers);
 };

From ea088cf56af67a500a59941257832c2289098138 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Tue, 2 Jan 2018 11:09:58 -0800
Subject: [PATCH 04/19] Removed JestAssertionError export (as it is no longer
 needed)

---
 packages/expect/src/index.js | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/expect/src/index.js b/packages/expect/src/index.js
index b8fc57d237d5..9560905dd132 100644
--- a/packages/expect/src/index.js
+++ b/packages/expect/src/index.js
@@ -298,8 +298,4 @@ expect.getState = getState;
 expect.setState = setState;
 expect.extractExpectedAssertionsErrors = extractExpectedAssertionsErrors;
 
-// Expose JestAssertionError for custom matchers
-// This enables them to preserve the stack for specific errors
-expect.JestAssertionError = JestAssertionError;
-
 module.exports = (expect: Expect);

From f2e733574f0ec31ebcfca26fc02b10a3fcb2b3cf Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Tue, 2 Jan 2018 11:43:03 -0800
Subject: [PATCH 05/19] Added custom matcher test

---
 .../__snapshots__/custom_matcher.test.js.snap | 15 +++++
 .../__tests__/custom_matcher.test.js          | 60 +++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
 create mode 100644 integration_tests/__tests__/custom_matcher.test.js

diff --git a/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap b/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
new file mode 100644
index 000000000000..78827557d8ad
--- /dev/null
+++ b/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Custom matcher preserves error stack 1`] = `
+"Error: qux
+    at baz (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:49:13)
+    at bar (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:47:23)
+    at foo (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:46:23)
+    at expect (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:54:9)
+    at Object.toCustomMatch (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:12:18)
+    at Object.throwingMatcher [as toCustomMatch] (/Users/bvaughn/Documents/git/jest/packages/expect/build/index.js:214:24)
+    at Object.it (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:55:10)
+    at Object.asyncFn (/Users/bvaughn/Documents/git/jest/packages/jest-jasmine2/build/jasmine_async.js:129:432)
+    at resolve (/Users/bvaughn/Documents/git/jest/packages/jest-jasmine2/build/queue_runner.js:51:12)
+    at Promise (<anonymous>)"
+`;
diff --git a/integration_tests/__tests__/custom_matcher.test.js b/integration_tests/__tests__/custom_matcher.test.js
new file mode 100644
index 000000000000..a251b25ac623
--- /dev/null
+++ b/integration_tests/__tests__/custom_matcher.test.js
@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+'use strict';
+
+function toCustomMatch(callback, expectation) {
+  const actual = callback();
+
+  if (actual !== expectation) {
+    return {
+      message: () => `Expected "${expectation}" but got "${actual}"`,
+      pass: false,
+    };
+  } else {
+    return {pass: true};
+  }
+}
+
+expect.extend({
+  toCustomMatch,
+});
+
+declare var expect: (func: Function) => any;
+
+describe('Custom matcher', () => {
+  // This test is expected to pass
+  it('passes', () => {
+    expect(() => 'foo').toCustomMatch('foo');
+  });
+
+  // This test is expected to fail
+  it('fails', () => {
+    expect(() => {
+      expect(() => 'foo').toCustomMatch('bar');
+    }).toThrow();
+  });
+
+  // This test fails due to an unrelated/unexpected error
+  // It will show a helpful stack trace though
+  it('preserves error stack', () => {
+    const foo = () => bar();
+    const bar = () => baz();
+    const baz = () => {
+      throw Error('qux');
+    };
+
+    try {
+      expect(() => {
+        foo();
+      }).toCustomMatch('test');
+    } catch (error) {
+      expect(error.stack).toMatchSnapshot();
+    }
+  });
+});

From 3e007538f815ab01153dfd7c6ae1741e32339493 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Wed, 3 Jan 2018 08:57:54 -0800
Subject: [PATCH 06/19] Adjusted custom_matcher test to use prettified,
 non-absolute stack

---
 .../__snapshots__/custom_matcher.test.js.snap | 25 +++++++++++--------
 .../__tests__/custom_matcher.test.js          | 15 +++++++++--
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap b/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
index 78827557d8ad..f1bee3069f56 100644
--- a/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
@@ -1,15 +1,18 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Custom matcher preserves error stack 1`] = `
-"Error: qux
-    at baz (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:49:13)
-    at bar (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:47:23)
-    at foo (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:46:23)
-    at expect (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:54:9)
-    at Object.toCustomMatch (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:12:18)
-    at Object.throwingMatcher [as toCustomMatch] (/Users/bvaughn/Documents/git/jest/packages/expect/build/index.js:214:24)
-    at Object.it (/Users/bvaughn/Documents/git/jest/integration_tests/__tests__/custom_matcher.test.js:55:10)
-    at Object.asyncFn (/Users/bvaughn/Documents/git/jest/packages/jest-jasmine2/build/jasmine_async.js:129:432)
-    at resolve (/Users/bvaughn/Documents/git/jest/packages/jest-jasmine2/build/queue_runner.js:51:12)
-    at Promise (<anonymous>)"
+"
+    </> <gray> 55 | </>    <cyan>const</> bar <yellow>=</> () <yellow>=></> baz()<yellow>;</></>
+    </> <gray> 56 | </>    <cyan>const</> baz <yellow>=</> () <yellow>=></> {</>
+    </><red><bold>></></><gray> 57 | </>      <cyan>throw</> <yellow>Error</>(<green>'qux'</>)<yellow>;</></>
+    </> <gray> 58 | </>    }<yellow>;</></>
+    </> <gray> 59 | </></>
+    </> <gray> 60 | </>    <cyan>try</> {</>
+      Error: qux
+      <dim>at baz (</>integration_tests/__tests__/custom_matcher.test.js<dim>:57:13)</>
+      <dim>at bar (</>integration_tests/__tests__/custom_matcher.test.js<dim>:55:23)</>
+      <dim>at foo (</>integration_tests/__tests__/custom_matcher.test.js<dim>:54:23)</>
+      <dim>at expect (</>integration_tests/__tests__/custom_matcher.test.js<dim>:62:9)</>
+      <dim>at Object.toCustomMatch (</>integration_tests/__tests__/custom_matcher.test.js<dim>:20:18)</>
+      <dim>at Object.it (</>integration_tests/__tests__/custom_matcher.test.js<dim>:63:10)</>"
 `;
diff --git a/integration_tests/__tests__/custom_matcher.test.js b/integration_tests/__tests__/custom_matcher.test.js
index a251b25ac623..cf29603b7adb 100644
--- a/integration_tests/__tests__/custom_matcher.test.js
+++ b/integration_tests/__tests__/custom_matcher.test.js
@@ -8,6 +8,14 @@
  */
 'use strict';
 
+import {formatStackTrace} from 'jest-message-util';
+import path from 'path';
+
+const rootDir = path.resolve(__dirname, '..', '..');
+
+const {makeProjectConfig} = require('../../test_utils');
+const projectConfig = makeProjectConfig({rootDir});
+
 function toCustomMatch(callback, expectation) {
   const actual = callback();
 
@@ -25,7 +33,7 @@ expect.extend({
   toCustomMatch,
 });
 
-declare var expect: (func: Function) => any;
+declare var expect: (any: any) => any;
 
 describe('Custom matcher', () => {
   // This test is expected to pass
@@ -54,7 +62,10 @@ describe('Custom matcher', () => {
         foo();
       }).toCustomMatch('test');
     } catch (error) {
-      expect(error.stack).toMatchSnapshot();
+      const stack = formatStackTrace(error.stack, projectConfig, {
+        noStackTrace: false,
+      });
+      expect(stack).toMatchSnapshot();
     }
   });
 });

From 9e0cfaee66e1668c7434c1896c6ed69a67248a27 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 22:11:20 +0100
Subject: [PATCH 07/19] test: refactor integration test

---
 .../__snapshots__/custom_matcher.test.js.snap | 18 --------------
 .../__snapshots__/stack_trace.test.js.snap    | 23 ++++++++++++++++++
 .../__tests__/stack_trace.test.js             |  6 +++++
 .../__tests__/custom_matcher.test.js          | 24 +++----------------
 4 files changed, 32 insertions(+), 39 deletions(-)
 delete mode 100644 integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
 rename integration_tests/{ => stack_trace}/__tests__/custom_matcher.test.js (66%)

diff --git a/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap b/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
deleted file mode 100644
index f1bee3069f56..000000000000
--- a/integration_tests/__tests__/__snapshots__/custom_matcher.test.js.snap
+++ /dev/null
@@ -1,18 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`Custom matcher preserves error stack 1`] = `
-"
-    </> <gray> 55 | </>    <cyan>const</> bar <yellow>=</> () <yellow>=></> baz()<yellow>;</></>
-    </> <gray> 56 | </>    <cyan>const</> baz <yellow>=</> () <yellow>=></> {</>
-    </><red><bold>></></><gray> 57 | </>      <cyan>throw</> <yellow>Error</>(<green>'qux'</>)<yellow>;</></>
-    </> <gray> 58 | </>    }<yellow>;</></>
-    </> <gray> 59 | </></>
-    </> <gray> 60 | </>    <cyan>try</> {</>
-      Error: qux
-      <dim>at baz (</>integration_tests/__tests__/custom_matcher.test.js<dim>:57:13)</>
-      <dim>at bar (</>integration_tests/__tests__/custom_matcher.test.js<dim>:55:23)</>
-      <dim>at foo (</>integration_tests/__tests__/custom_matcher.test.js<dim>:54:23)</>
-      <dim>at expect (</>integration_tests/__tests__/custom_matcher.test.js<dim>:62:9)</>
-      <dim>at Object.toCustomMatch (</>integration_tests/__tests__/custom_matcher.test.js<dim>:20:18)</>
-      <dim>at Object.it (</>integration_tests/__tests__/custom_matcher.test.js<dim>:63:10)</>"
-`;
diff --git a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
index 0e8075de198a..a1b10bb4d880 100644
--- a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
@@ -62,3 +62,26 @@ Time:        <<REPLACED>>
 Ran all test suites matching /runtime_error.test.js/i.
 "
 `;
+
+exports[`works with custom matchers 1`] = `
+"FAIL __tests__/custom_matcher.test.js
+  Custom matcher
+    ✓ passes
+    ✓ fails
+    ✕ preserves error stack
+
+  ● Custom matcher › preserves error stack
+
+    qux
+
+      49 |     expect(() => {
+      50 |       foo();
+    > 51 |     }).toCustomMatch('test');
+      52 |   });
+      53 | });
+      54 | 
+      
+      at __tests__/custom_matcher.test.js:51:8
+
+"
+`;
diff --git a/integration_tests/__tests__/stack_trace.test.js b/integration_tests/__tests__/stack_trace.test.js
index 7bf884b817c3..17ef282634e9 100644
--- a/integration_tests/__tests__/stack_trace.test.js
+++ b/integration_tests/__tests__/stack_trace.test.js
@@ -122,3 +122,9 @@ describe('Stack Trace', () => {
     );
   });
 });
+
+test('works with custom matchers', () => {
+  const {stderr} = runJest('stack_trace', ['custom_matcher.test.js']);
+
+  expect(extractSummary(stderr).rest).toMatchSnapshot();
+});
diff --git a/integration_tests/__tests__/custom_matcher.test.js b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
similarity index 66%
rename from integration_tests/__tests__/custom_matcher.test.js
rename to integration_tests/stack_trace/__tests__/custom_matcher.test.js
index cf29603b7adb..472c677dd161 100644
--- a/integration_tests/__tests__/custom_matcher.test.js
+++ b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
@@ -4,18 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow
  */
 'use strict';
 
-import {formatStackTrace} from 'jest-message-util';
-import path from 'path';
-
-const rootDir = path.resolve(__dirname, '..', '..');
-
-const {makeProjectConfig} = require('../../test_utils');
-const projectConfig = makeProjectConfig({rootDir});
-
 function toCustomMatch(callback, expectation) {
   const actual = callback();
 
@@ -33,8 +24,6 @@ expect.extend({
   toCustomMatch,
 });
 
-declare var expect: (any: any) => any;
-
 describe('Custom matcher', () => {
   // This test is expected to pass
   it('passes', () => {
@@ -57,15 +46,8 @@ describe('Custom matcher', () => {
       throw Error('qux');
     };
 
-    try {
-      expect(() => {
-        foo();
-      }).toCustomMatch('test');
-    } catch (error) {
-      const stack = formatStackTrace(error.stack, projectConfig, {
-        noStackTrace: false,
-      });
-      expect(stack).toMatchSnapshot();
-    }
+    expect(() => {
+      foo();
+    }).toCustomMatch('test');
   });
 });

From 31f8e58bf2d2f6ba6d6bb6236e4095f77552ff8e Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 22:17:49 +0100
Subject: [PATCH 08/19] update with correct snapshot

---
 .../__snapshots__/stack_trace.test.js.snap        | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
index a1b10bb4d880..3101a7284e27 100644
--- a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
@@ -74,13 +74,18 @@ exports[`works with custom matchers 1`] = `
 
     qux
 
+      44 |     const bar = () => baz();
+      45 |     const baz = () => {
+    > 46 |       throw Error('qux');
+      47 |     };
+      48 | 
       49 |     expect(() => {
-      50 |       foo();
-    > 51 |     }).toCustomMatch('test');
-      52 |   });
-      53 | });
-      54 | 
       
+      at __tests__/custom_matcher.test.js:46:13
+      at __tests__/custom_matcher.test.js:44:23
+      at __tests__/custom_matcher.test.js:43:23
+      at __tests__/custom_matcher.test.js:50:7
+      at __tests__/custom_matcher.test.js:11:18
       at __tests__/custom_matcher.test.js:51:8
 
 "

From c388a493e852aa41780ac4965738a87e6a71d217 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 22:29:52 +0100
Subject: [PATCH 09/19] test: skip on windows

---
 integration_tests/__tests__/stack_trace.test.js | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/integration_tests/__tests__/stack_trace.test.js b/integration_tests/__tests__/stack_trace.test.js
index 17ef282634e9..a8f9162f5c9d 100644
--- a/integration_tests/__tests__/stack_trace.test.js
+++ b/integration_tests/__tests__/stack_trace.test.js
@@ -10,6 +10,7 @@
 
 const runJest = require('../runJest');
 const {extractSummary} = require('../utils');
+const skipOnWindows = require('../../scripts/skip_on_windows');
 
 describe('Stack Trace', () => {
   it('prints a stack trace for runtime errors', () => {
@@ -124,6 +125,10 @@ describe('Stack Trace', () => {
 });
 
 test('works with custom matchers', () => {
+  if (skipOnWindows.test()) {
+    return;
+  }
+
   const {stderr} = runJest('stack_trace', ['custom_matcher.test.js']);
 
   expect(extractSummary(stderr).rest).toMatchSnapshot();

From 0c5c78c5f5a11f6d2008cf1cac6df22b024548e5 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Wed, 3 Jan 2018 13:46:54 -0800
Subject: [PATCH 10/19] Clarified comment

---
 .../stack_trace/__tests__/custom_matcher.test.js             | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/integration_tests/stack_trace/__tests__/custom_matcher.test.js b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
index 472c677dd161..1939049f3d1f 100644
--- a/integration_tests/stack_trace/__tests__/custom_matcher.test.js
+++ b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
@@ -25,14 +25,15 @@ expect.extend({
 });
 
 describe('Custom matcher', () => {
-  // This test is expected to pass
   it('passes', () => {
+    // This expectation should pass
     expect(() => 'foo').toCustomMatch('foo');
   });
 
-  // This test is expected to fail
   it('fails', () => {
     expect(() => {
+      // This expectation should fail,
+      // Which is why it's wrapped in a .toThrow() block.
       expect(() => 'foo').toCustomMatch('bar');
     }).toThrow();
   });

From 5843ab5db5681a8bbaaa3e1f910bd2636d9c9bc5 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Wed, 3 Jan 2018 13:47:56 -0800
Subject: [PATCH 11/19] Further clarified comment

---
 .../stack_trace/__tests__/custom_matcher.test.js             | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/integration_tests/stack_trace/__tests__/custom_matcher.test.js b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
index 1939049f3d1f..b7fe8130c532 100644
--- a/integration_tests/stack_trace/__tests__/custom_matcher.test.js
+++ b/integration_tests/stack_trace/__tests__/custom_matcher.test.js
@@ -38,8 +38,6 @@ describe('Custom matcher', () => {
     }).toThrow();
   });
 
-  // This test fails due to an unrelated/unexpected error
-  // It will show a helpful stack trace though
   it('preserves error stack', () => {
     const foo = () => bar();
     const bar = () => baz();
@@ -47,6 +45,9 @@ describe('Custom matcher', () => {
       throw Error('qux');
     };
 
+    // This expecation fails due to an error we throw (intentionally)
+    // The stack trace should point to the line that throws the error though,
+    // Not to the line that calls the matcher.
     expect(() => {
       foo();
     }).toCustomMatch('test');

From f902b4b9913bbdf0c5fbcde1f21d81dc33c01e2c Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 22:52:29 +0100
Subject: [PATCH 12/19] test: fix test for node 6

---
 .../__snapshots__/stack_trace.test.js.snap    | 20 +++++++++----------
 packages/jest-message-util/src/index.js       |  7 ++++++-
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
index 3101a7284e27..0a2d923142ea 100644
--- a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
@@ -74,19 +74,19 @@ exports[`works with custom matchers 1`] = `
 
     qux
 
-      44 |     const bar = () => baz();
-      45 |     const baz = () => {
-    > 46 |       throw Error('qux');
-      47 |     };
-      48 | 
-      49 |     expect(() => {
+      43 |     const bar = () => baz();
+      44 |     const baz = () => {
+    > 45 |       throw Error('qux');
+      46 |     };
+      47 | 
+      48 |     // This expecation fails due to an error we throw (intentionally)
       
-      at __tests__/custom_matcher.test.js:46:13
-      at __tests__/custom_matcher.test.js:44:23
+      at __tests__/custom_matcher.test.js:45:13
       at __tests__/custom_matcher.test.js:43:23
-      at __tests__/custom_matcher.test.js:50:7
+      at __tests__/custom_matcher.test.js:42:23
+      at __tests__/custom_matcher.test.js:52:7
       at __tests__/custom_matcher.test.js:11:18
-      at __tests__/custom_matcher.test.js:51:8
+      at __tests__/custom_matcher.test.js:53:8
 
 "
 `;
diff --git a/packages/jest-message-util/src/index.js b/packages/jest-message-util/src/index.js
index ec9461dff078..9656c3fcd625 100644
--- a/packages/jest-message-util/src/index.js
+++ b/packages/jest-message-util/src/index.js
@@ -51,13 +51,14 @@ const ANONYMOUS_FN_IGNORE = /^\s+at <anonymous>.*$/;
 const ANONYMOUS_PROMISE_IGNORE = /^\s+at (new )?Promise \(<anonymous>\).*$/;
 const ANONYMOUS_GENERATOR_IGNORE = /^\s+at Generator.next \(<anonymous>\).*$/;
 const NATIVE_NEXT_IGNORE = /^\s+at next \(native\).*$/;
+const NATIVE_ERROR_IGNORE = /^\s+at Error \(native\).*$/;
 const TITLE_INDENT = '  ';
 const MESSAGE_INDENT = '    ';
 const STACK_INDENT = '      ';
 const ANCESTRY_SEPARATOR = ' \u203A ';
 const TITLE_BULLET = chalk.bold('\u25cf ');
 const STACK_TRACE_COLOR = chalk.dim;
-const STACK_PATH_REGEXP = /\s*at.*\(?(\:\d*\:\d*|native)\)?/;
+const STACK_PATH_REGEXP = /\s*at.*\(?(:\d*:\d*|native)\)?/;
 const EXEC_ERROR_MESSAGE = 'Test suite failed to run';
 const ERROR_TEXT = 'Error: ';
 
@@ -146,6 +147,10 @@ const removeInternalStackEntries = (lines, options: StackTraceOptions) => {
       return false;
     }
 
+    if (NATIVE_ERROR_IGNORE.test(line)) {
+      return false;
+    }
+
     if (nodeInternals.some(internal => internal.test(line))) {
       return false;
     }

From bd219226fd94f6e149a23fe86a5badecb8e7fea9 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 23:22:59 +0100
Subject: [PATCH 13/19] test: move custom matcher stack to separate file to be
 able to skip it on windows

---
 .../custom_matcher_stack_trace.test.js.snap   | 29 +++++++++++++++++++
 .../__snapshots__/stack_trace.test.js.snap    | 28 ------------------
 .../custom_matcher_stack_trace.test.js        | 25 ++++++++++++++++
 .../__tests__/stack_trace.test.js             | 11 -------
 .../__tests__/custom_matcher.test.js          |  0
 .../custom_matcher_stack_trace/package.json   |  5 ++++
 6 files changed, 59 insertions(+), 39 deletions(-)
 create mode 100644 integration_tests/__tests__/__snapshots__/custom_matcher_stack_trace.test.js.snap
 create mode 100644 integration_tests/__tests__/custom_matcher_stack_trace.test.js
 rename integration_tests/{stack_trace => custom_matcher_stack_trace}/__tests__/custom_matcher.test.js (100%)
 create mode 100644 integration_tests/custom_matcher_stack_trace/package.json

diff --git a/integration_tests/__tests__/__snapshots__/custom_matcher_stack_trace.test.js.snap b/integration_tests/__tests__/__snapshots__/custom_matcher_stack_trace.test.js.snap
new file mode 100644
index 000000000000..5e6181192e26
--- /dev/null
+++ b/integration_tests/__tests__/__snapshots__/custom_matcher_stack_trace.test.js.snap
@@ -0,0 +1,29 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`works with custom matchers 1`] = `
+"FAIL __tests__/custom_matcher.test.js
+  Custom matcher
+    ✓ passes
+    ✓ fails
+    ✕ preserves error stack
+
+  ● Custom matcher › preserves error stack
+
+    qux
+
+      43 |     const bar = () => baz();
+      44 |     const baz = () => {
+    > 45 |       throw Error('qux');
+      46 |     };
+      47 | 
+      48 |     // This expecation fails due to an error we throw (intentionally)
+      
+      at __tests__/custom_matcher.test.js:45:13
+      at __tests__/custom_matcher.test.js:43:23
+      at __tests__/custom_matcher.test.js:42:23
+      at __tests__/custom_matcher.test.js:52:7
+      at __tests__/custom_matcher.test.js:11:18
+      at __tests__/custom_matcher.test.js:53:8
+
+"
+`;
diff --git a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
index 0a2d923142ea..0e8075de198a 100644
--- a/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/stack_trace.test.js.snap
@@ -62,31 +62,3 @@ Time:        <<REPLACED>>
 Ran all test suites matching /runtime_error.test.js/i.
 "
 `;
-
-exports[`works with custom matchers 1`] = `
-"FAIL __tests__/custom_matcher.test.js
-  Custom matcher
-    ✓ passes
-    ✓ fails
-    ✕ preserves error stack
-
-  ● Custom matcher › preserves error stack
-
-    qux
-
-      43 |     const bar = () => baz();
-      44 |     const baz = () => {
-    > 45 |       throw Error('qux');
-      46 |     };
-      47 | 
-      48 |     // This expecation fails due to an error we throw (intentionally)
-      
-      at __tests__/custom_matcher.test.js:45:13
-      at __tests__/custom_matcher.test.js:43:23
-      at __tests__/custom_matcher.test.js:42:23
-      at __tests__/custom_matcher.test.js:52:7
-      at __tests__/custom_matcher.test.js:11:18
-      at __tests__/custom_matcher.test.js:53:8
-
-"
-`;
diff --git a/integration_tests/__tests__/custom_matcher_stack_trace.test.js b/integration_tests/__tests__/custom_matcher_stack_trace.test.js
new file mode 100644
index 000000000000..a3a3128dd0a3
--- /dev/null
+++ b/integration_tests/__tests__/custom_matcher_stack_trace.test.js
@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+'use strict';
+
+const runJest = require('../runJest');
+const {extractSummary} = require('../utils');
+const skipOnWindows = require('../../scripts/skip_on_windows');
+
+skipOnWindows.suite();
+
+test('works with custom matchers', () => {
+  if (skipOnWindows.test()) {
+    return;
+  }
+
+  const {stderr} = runJest('custom_matcher_stack_trace');
+
+  expect(extractSummary(stderr).rest).toMatchSnapshot();
+});
diff --git a/integration_tests/__tests__/stack_trace.test.js b/integration_tests/__tests__/stack_trace.test.js
index a8f9162f5c9d..7bf884b817c3 100644
--- a/integration_tests/__tests__/stack_trace.test.js
+++ b/integration_tests/__tests__/stack_trace.test.js
@@ -10,7 +10,6 @@
 
 const runJest = require('../runJest');
 const {extractSummary} = require('../utils');
-const skipOnWindows = require('../../scripts/skip_on_windows');
 
 describe('Stack Trace', () => {
   it('prints a stack trace for runtime errors', () => {
@@ -123,13 +122,3 @@ describe('Stack Trace', () => {
     );
   });
 });
-
-test('works with custom matchers', () => {
-  if (skipOnWindows.test()) {
-    return;
-  }
-
-  const {stderr} = runJest('stack_trace', ['custom_matcher.test.js']);
-
-  expect(extractSummary(stderr).rest).toMatchSnapshot();
-});
diff --git a/integration_tests/stack_trace/__tests__/custom_matcher.test.js b/integration_tests/custom_matcher_stack_trace/__tests__/custom_matcher.test.js
similarity index 100%
rename from integration_tests/stack_trace/__tests__/custom_matcher.test.js
rename to integration_tests/custom_matcher_stack_trace/__tests__/custom_matcher.test.js
diff --git a/integration_tests/custom_matcher_stack_trace/package.json b/integration_tests/custom_matcher_stack_trace/package.json
new file mode 100644
index 000000000000..148788b25446
--- /dev/null
+++ b/integration_tests/custom_matcher_stack_trace/package.json
@@ -0,0 +1,5 @@
+{
+  "jest": {
+    "testEnvironment": "node"
+  }
+}

From 3ef09ea4b710591363311335114ee0d600138c4f Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 23:36:21 +0100
Subject: [PATCH 14/19] Revert "test: fix test for node 6"

This reverts commit f902b4b9913bbdf0c5fbcde1f21d81dc33c01e2c.
---
 packages/jest-message-util/src/index.js | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/packages/jest-message-util/src/index.js b/packages/jest-message-util/src/index.js
index 9656c3fcd625..ec9461dff078 100644
--- a/packages/jest-message-util/src/index.js
+++ b/packages/jest-message-util/src/index.js
@@ -51,14 +51,13 @@ const ANONYMOUS_FN_IGNORE = /^\s+at <anonymous>.*$/;
 const ANONYMOUS_PROMISE_IGNORE = /^\s+at (new )?Promise \(<anonymous>\).*$/;
 const ANONYMOUS_GENERATOR_IGNORE = /^\s+at Generator.next \(<anonymous>\).*$/;
 const NATIVE_NEXT_IGNORE = /^\s+at next \(native\).*$/;
-const NATIVE_ERROR_IGNORE = /^\s+at Error \(native\).*$/;
 const TITLE_INDENT = '  ';
 const MESSAGE_INDENT = '    ';
 const STACK_INDENT = '      ';
 const ANCESTRY_SEPARATOR = ' \u203A ';
 const TITLE_BULLET = chalk.bold('\u25cf ');
 const STACK_TRACE_COLOR = chalk.dim;
-const STACK_PATH_REGEXP = /\s*at.*\(?(:\d*:\d*|native)\)?/;
+const STACK_PATH_REGEXP = /\s*at.*\(?(\:\d*\:\d*|native)\)?/;
 const EXEC_ERROR_MESSAGE = 'Test suite failed to run';
 const ERROR_TEXT = 'Error: ';
 
@@ -147,10 +146,6 @@ const removeInternalStackEntries = (lines, options: StackTraceOptions) => {
       return false;
     }
 
-    if (NATIVE_ERROR_IGNORE.test(line)) {
-      return false;
-    }
-
     if (nodeInternals.some(internal => internal.test(line))) {
       return false;
     }

From f88bf07b3971e0fb73f2997c68d8c92c60748ed9 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Wed, 3 Jan 2018 23:36:36 +0100
Subject: [PATCH 15/19] test: really fix node 6

---
 .../__tests__/custom_matcher_stack_trace.test.js    | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/integration_tests/__tests__/custom_matcher_stack_trace.test.js b/integration_tests/__tests__/custom_matcher_stack_trace.test.js
index a3a3128dd0a3..fb4d9f817ce4 100644
--- a/integration_tests/__tests__/custom_matcher_stack_trace.test.js
+++ b/integration_tests/__tests__/custom_matcher_stack_trace.test.js
@@ -15,11 +15,14 @@ const skipOnWindows = require('../../scripts/skip_on_windows');
 skipOnWindows.suite();
 
 test('works with custom matchers', () => {
-  if (skipOnWindows.test()) {
-    return;
-  }
-
   const {stderr} = runJest('custom_matcher_stack_trace');
 
-  expect(extractSummary(stderr).rest).toMatchSnapshot();
+  let {rest} = extractSummary(stderr);
+
+  rest = rest
+    .split('\n')
+    .filter(line => line.indexOf('at Error (native)') < 0)
+    .join('\n');
+
+  expect(rest).toMatchSnapshot();
 });

From 2da0eeed9cdb72b4a7b44cf060f5cbabf20d013e Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Thu, 4 Jan 2018 11:14:16 +0100
Subject: [PATCH 16/19] docs: add package prefix to changelog

also format all markdown files
---
 CHANGELOG.md             |  7 ++++---
 docs/Configuration.md    |  9 ++++-----
 docs/SetupAndTeardown.md | 13 +++++++++----
 3 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75af2c12240c..df4bf6668576 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,8 +8,8 @@
   Windows platform. ([#5161](https://github.com/facebook/jest/pull/5161))
 * `[jest-regex-util]` Fix breaking change in `--testPathPattern`
   ([#5230](https://github.com/facebook/jest/pull/5230))
-* Do not override `Error` stack (with `Error.captureStackTrace`) for custom matchers.
-  ([#5162](https://github.com/facebook/jest/pull/5162))
+* `[expect]` Do not override `Error` stack (with `Error.captureStackTrace`) for
+  custom matchers. ([#5162](https://github.com/facebook/jest/pull/5162))
 
 ### Features
 
@@ -22,7 +22,8 @@
 
 ### Chore & Maintenance
 
-* `[docs]` Describe the order of execution of describe and test blocks, and a note on using `test.concurrent`.
+* `[docs]` Describe the order of execution of describe and test blocks, and a
+  note on using `test.concurrent`.
   ([#5217](https://github.com/facebook/jest/pull/5217))
 
 ## jest 22.0.4
diff --git a/docs/Configuration.md b/docs/Configuration.md
index 2c5cf6fb52b4..e27dbf7c84dd 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -792,9 +792,9 @@ test('use jsdom in this test file', () => {
 
 You can create your own module that will be used for setting up the test
 environment. The module must export a class with `setup`, `teardown` and
-`runScript` methods. You can also pass variables from this module to your
-test suites by assigning them to `this.global` object &ndash; this will
-make them available in your test suites as global variables.
+`runScript` methods. You can also pass variables from this module to your test
+suites by assigning them to `this.global` object &ndash; this will make them
+available in your test suites as global variables.
 
 ##### available in Jest **22.0.0+**
 
@@ -836,8 +836,7 @@ let someGlobalObject;
 
 beforeAll(() => {
   someGlobalObject = global.someGlobalObject;
-})
-
+});
 ```
 
 ### `testEnvironmentOptions` [Object]
diff --git a/docs/SetupAndTeardown.md b/docs/SetupAndTeardown.md
index e4dbe65352d4..9ff92467e100 100644
--- a/docs/SetupAndTeardown.md
+++ b/docs/SetupAndTeardown.md
@@ -149,7 +149,12 @@ describe('Scoped / Nested block', () => {
 
 ### Order of execution of describe and test blocks
 
-Jest executes all describe handlers in a test file *before* it executes any of the actual tests. This is another reason to do setup and teardown in `before*` and `after*` handlers rather in the describe blocks. Once the describe blocks are complete, by default Jest runs all the tests serially in the order they were encountered in the collection phase, waiting for each to finish and be tidied up before moving on. 
+Jest executes all describe handlers in a test file _before_ it executes any of
+the actual tests. This is another reason to do setup and teardown in `before*`
+and `after*` handlers rather in the describe blocks. Once the describe blocks
+are complete, by default Jest runs all the tests serially in the order they were
+encountered in the collection phase, waiting for each to finish and be tidied up
+before moving on.
 
 Consider the following illustrative test file and output:
 
@@ -157,7 +162,7 @@ Consider the following illustrative test file and output:
 describe('outer', () => {
 
  console.log(`describe outer-a`);
- 
+
  describe('describe inner 1', () => {
    console.log(`describe inner 1`);
    test('test 1', () => {
@@ -167,7 +172,7 @@ describe('outer', () => {
  });
 
  console.log(`describe outer-b`);
- 
+
  test('test 1', () => {
    console.log(`test for describe outer`);
    expect(true).toEqual(true);
@@ -180,7 +185,7 @@ describe('outer', () => {
      expect(false).toEqual(false);
    })
  });
- 
+
  console.log(`describe outer-c`);
 });
 

From e8ab539e058b110e34f5a8ba980a3a44f4403d5f Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Thu, 4 Jan 2018 10:01:18 -0800
Subject: [PATCH 17/19] Reverted unrelated Markdown changes that had made their
 way into the branch

---
 CHANGELOG.md             |  3 +--
 docs/Configuration.md    |  9 +++++----
 docs/SetupAndTeardown.md | 13 ++++---------
 3 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df4bf6668576..8339e59ac8a0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,8 +22,7 @@
 
 ### Chore & Maintenance
 
-* `[docs]` Describe the order of execution of describe and test blocks, and a
-  note on using `test.concurrent`.
+* `[docs]` Describe the order of execution of describe and test blocks, and a note on using `test.concurrent`.
   ([#5217](https://github.com/facebook/jest/pull/5217))
 
 ## jest 22.0.4
diff --git a/docs/Configuration.md b/docs/Configuration.md
index e27dbf7c84dd..2c5cf6fb52b4 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -792,9 +792,9 @@ test('use jsdom in this test file', () => {
 
 You can create your own module that will be used for setting up the test
 environment. The module must export a class with `setup`, `teardown` and
-`runScript` methods. You can also pass variables from this module to your test
-suites by assigning them to `this.global` object &ndash; this will make them
-available in your test suites as global variables.
+`runScript` methods. You can also pass variables from this module to your
+test suites by assigning them to `this.global` object &ndash; this will
+make them available in your test suites as global variables.
 
 ##### available in Jest **22.0.0+**
 
@@ -836,7 +836,8 @@ let someGlobalObject;
 
 beforeAll(() => {
   someGlobalObject = global.someGlobalObject;
-});
+})
+
 ```
 
 ### `testEnvironmentOptions` [Object]
diff --git a/docs/SetupAndTeardown.md b/docs/SetupAndTeardown.md
index 9ff92467e100..e4dbe65352d4 100644
--- a/docs/SetupAndTeardown.md
+++ b/docs/SetupAndTeardown.md
@@ -149,12 +149,7 @@ describe('Scoped / Nested block', () => {
 
 ### Order of execution of describe and test blocks
 
-Jest executes all describe handlers in a test file _before_ it executes any of
-the actual tests. This is another reason to do setup and teardown in `before*`
-and `after*` handlers rather in the describe blocks. Once the describe blocks
-are complete, by default Jest runs all the tests serially in the order they were
-encountered in the collection phase, waiting for each to finish and be tidied up
-before moving on.
+Jest executes all describe handlers in a test file *before* it executes any of the actual tests. This is another reason to do setup and teardown in `before*` and `after*` handlers rather in the describe blocks. Once the describe blocks are complete, by default Jest runs all the tests serially in the order they were encountered in the collection phase, waiting for each to finish and be tidied up before moving on. 
 
 Consider the following illustrative test file and output:
 
@@ -162,7 +157,7 @@ Consider the following illustrative test file and output:
 describe('outer', () => {
 
  console.log(`describe outer-a`);
-
+ 
  describe('describe inner 1', () => {
    console.log(`describe inner 1`);
    test('test 1', () => {
@@ -172,7 +167,7 @@ describe('outer', () => {
  });
 
  console.log(`describe outer-b`);
-
+ 
  test('test 1', () => {
    console.log(`test for describe outer`);
    expect(true).toEqual(true);
@@ -185,7 +180,7 @@ describe('outer', () => {
      expect(false).toEqual(false);
    })
  });
-
+ 
  console.log(`describe outer-c`);
 });
 

From 7dad4663b6b22b8a726964d6ca2ee4f53a1daa64 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Thu, 4 Jan 2018 10:14:24 -0800
Subject: [PATCH 18/19] Replaced '__jestInternal' string attribute with a
 Symbol

---
 packages/expect/src/index.js                | 3 ++-
 packages/expect/src/jest_matchers_object.js | 6 +++++-
 types/Matchers.js                           | 1 -
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/expect/src/index.js b/packages/expect/src/index.js
index 9560905dd132..a74ffffa13c8 100644
--- a/packages/expect/src/index.js
+++ b/packages/expect/src/index.js
@@ -34,6 +34,7 @@ import {
   stringMatching,
 } from './asymmetric_matchers';
 import {
+  INTERNAL_MATCHER_FLAG,
   getState,
   setState,
   getMatchers,
@@ -214,7 +215,7 @@ const makeThrowingMatcher = (
       result = matcher.apply(matcherContext, [actual].concat(args));
     } catch (error) {
       if (
-        matcher.__jestInternal === true &&
+        matcher[INTERNAL_MATCHER_FLAG] === true &&
         !(error instanceof JestAssertionError) &&
         error.name !== 'PrettyFormatPluginError' &&
         // Guard for some environments (browsers) that do not support this feature.
diff --git a/packages/expect/src/jest_matchers_object.js b/packages/expect/src/jest_matchers_object.js
index fb7ca10d23c6..29c374279436 100644
--- a/packages/expect/src/jest_matchers_object.js
+++ b/packages/expect/src/jest_matchers_object.js
@@ -13,6 +13,10 @@ import type {MatchersObject} from 'types/Matchers';
 // the state, that can hold matcher specific values that change over time.
 const JEST_MATCHERS_OBJECT = Symbol.for('$$jest-matchers-object');
 
+// Notes a built-in/internal Jest matcher.
+// Jest may override the stack trace of Errors thrown by internal matchers.
+export const INTERNAL_MATCHER_FLAG = Symbol.for('$$jest-internal-matcher');
+
 if (!global[JEST_MATCHERS_OBJECT]) {
   Object.defineProperty(global, JEST_MATCHERS_OBJECT, {
     value: {
@@ -38,7 +42,7 @@ export const getMatchers = () => global[JEST_MATCHERS_OBJECT].matchers;
 export const setMatchers = (matchers: MatchersObject, isInternal: boolean) => {
   Object.keys(matchers).forEach(key => {
     const matcher = matchers[key];
-    Object.defineProperty(matcher, '__jestInternal', {
+    Object.defineProperty(matcher, INTERNAL_MATCHER_FLAG, {
       value: isInternal,
     });
   });
diff --git a/types/Matchers.js b/types/Matchers.js
index b4824891e56f..04e11e5b0939 100644
--- a/types/Matchers.js
+++ b/types/Matchers.js
@@ -19,7 +19,6 @@ export type RawMatcherFn = (
   expected: any,
   actual: any,
   options: any,
-  __jestInternal?: boolean,
 ) => ExpectationResult;
 
 export type ThrowingMatcherFn = (actual: any) => void;

From b8c6bfedea1c74f8b36a086e8f395271e589d7f2 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <brian.david.vaughn@gmail.com>
Date: Fri, 5 Jan 2018 09:21:36 -0800
Subject: [PATCH 19/19] Updated snapshot

---
 integration_tests/__tests__/__snapshots__/failures.test.js.snap | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/integration_tests/__tests__/__snapshots__/failures.test.js.snap b/integration_tests/__tests__/__snapshots__/failures.test.js.snap
index 77081dc783e5..b2c5d619caa8 100644
--- a/integration_tests/__tests__/__snapshots__/failures.test.js.snap
+++ b/integration_tests/__tests__/__snapshots__/failures.test.js.snap
@@ -118,7 +118,7 @@ exports[`works with async failures 1`] = `
     +   \\"foo\\": \\"bar\\",
       }
       
-      at ../../packages/expect/build/index.js:155:54
+      at ../../packages/expect/build/index.js:156:54
 
 "
 `;