diff --git a/axe.d.ts b/axe.d.ts
index 8554f4381d..85b6ecfad7 100644
--- a/axe.d.ts
+++ b/axe.d.ts
@@ -265,7 +265,7 @@ declare namespace axe {
frameContext: ContextObject;
}
interface Utils {
- getFrameContexts: (context?: ElementContext) => FrameContext[];
+ getFrameContexts: (context?: ElementContext, options?: RunOptions) => FrameContext[];
shadowSelect: (selector: CrossTreeSelector) => Element | null;
}
interface EnvironmentData {
diff --git a/doc/run-partial.md b/doc/run-partial.md
index 011edf4a85..e0b09838df 100644
--- a/doc/run-partial.md
+++ b/doc/run-partial.md
@@ -23,7 +23,7 @@ When using `axe.runPartial()` it is important to keep in mind that the `context`
function runPartialRecursive(context, options = {}, win = window) {
const { axe, document } = win;
// Find all frames in context, and determine what context object to use in that frame
- const frameContexts = axe.utils.getFrameContexts(context);
+ const frameContexts = axe.utils.getFrameContexts(context, options);
// Run the current context, in the current window.
const promiseResults = [ axe.runPartial(context, options) ];
@@ -75,13 +75,15 @@ axe.finishRun([
**important**: Since `axe.finishRun` may have access to cross-origin information, it should only be called in an environment that is known not to have third-party scripts. When using a browser driver, this can for example by done in a blank page.
-## axe.utils.getFrameContexts(context): FrameContext[]
+## axe.utils.getFrameContexts(context, options): FrameContext[]
The `axe.utils.getFrameContexts` method takes any valid context, and returns an array of objects. Each object represents a frame that is in the context. The object has the following properties:
- `frameSelector`: This is a CSS selector, or array of CSS selectors in case of nodes in a shadow DOM tree to locate the frame element to be tested.
- `frameContext`: This is an object is a context object that should be tested in the particular frame.
+The `options` object takes the same RunOptions object that axe.run accepts. When the `iframes` property is `false`, it returns an empty array.
+
## Custom Rulesets and Reporters
Because `axe.finishRun` does not run inside the page, the `reporter` and `after` methods do not have access to the top-level `window` and `document` objects, and might not have access to common browser APIs. Axe-core reporter use the `environmentData` property that is set on the partialResult object of the initiator.
diff --git a/lib/core/utils/get-frame-contexts.js b/lib/core/utils/get-frame-contexts.js
index be88061a35..e12a69d485 100644
--- a/lib/core/utils/get-frame-contexts.js
+++ b/lib/core/utils/get-frame-contexts.js
@@ -1,7 +1,11 @@
import Context from '../base/context';
import getAncestry from './get-ancestry';
-export default function getFrameContexts(context) {
+export default function getFrameContexts(context, options = {}) {
+ if (options.iframes === false) {
+ return [];
+ }
+
const { frames } = new Context(context);
return frames.map(({ node, ...frameContext }) => {
frameContext.initiator = false;
diff --git a/test/core/utils/get-frame-contexts.js b/test/core/utils/get-frame-contexts.js
index b2b3443ed5..2c0367b0fa 100644
--- a/test/core/utils/get-frame-contexts.js
+++ b/test/core/utils/get-frame-contexts.js
@@ -265,4 +265,18 @@ describe('utils.getFrameContexts', function() {
assert.deepEqual(frameContext[0].frameContext.exclude, []);
});
});
+
+ describe('options.iframes', function () {
+ it('returns a non-empty array with `iframes: true`', function() {
+ fixture.innerHTML = '';
+ var contexts = getFrameContexts({}, { iframes: true })
+ assert.lengthOf(contexts, 1);
+ });
+
+ it('returns an empty array with `iframes: false`', function () {
+ fixture.innerHTML = '';
+ var contexts = getFrameContexts({}, { iframes: false })
+ assert.lengthOf(contexts, 0);
+ });
+ });
});