Fix ignore url handling

lib/pa11y.js

@@ -19,7 +19,7 @@ module.exports = pa11y;
 /**
  * Run accessibility tests on a web page.
  * @public
- * @param {String} url - The URL to run tests against.
+ * @param {(String|Object)} url - The URL to run tests against, or options object.
  * @param {Object} [options={}] - Options to change the way tests run.
  * @param {Function} [callback] - An optional callback to use instead of promises.
  * @returns {Promise} Returns a promise which resolves with a results object.
@@ -34,6 +34,11 @@ async function pa11y(url, options = {}, callback) {
 		// Verify that the given options are valid
 		verifyOptions(options);
 
+		if (!url && !options.ignoreUrl) {
+			// eslint-disable-next-line max-len
+			throw new Error('A url must be defined via the `url` parameter or `options.url`, or `options.ignoreUrl` must be set to true.');
+		}
+
 		// Call the actual Pa11y test runner with
 		// a timeout if it takes too long
 		pa11yResults = await promiseTimeout(
@@ -58,7 +63,7 @@ async function pa11y(url, options = {}, callback) {
 /**
  * Parse arguments from the command-line to properly identify the url, options, and callback
  * @private
- * @param {String} url - The URL to run tests against.
+ * @param {(String|Object)} url - The URL to run tests against, or options object.
  * @param {Object} [options={}] - Options to change the way tests run.
  * @param {Function} [callback] - An optional callback to use instead of promises.
  * @returns {Array} the new values of url, options, and callback
@@ -68,11 +73,13 @@ function parseArguments(url, options, callback) {
 		callback = options;
 		options = {};
 	}
-	if (typeof url !== 'string') {
-		options = url;
-		url = options.url;
+	if (url) {
+		if (typeof url !== 'string') {
+			options = url;
+			url = options.url;
+		}
+		url = sanitizeUrl(url);
 	}
-	url = sanitizeUrl(url);
 	options = defaultOptions(options);
 
 	return [url,
@@ -109,7 +116,9 @@ function defaultOptions(options) {
  */
 async function runPa11yTest(url, options, state) {
 
-	options.log.info(`Running Pa11y on URL ${url}`);
+	if (url) {
+		options.log.info(`Running Pa11y on URL ${url}`);
+	}
 
 	await setBrowser(options, state);
 
@@ -513,6 +522,7 @@ pa11y.defaults = {
 		info: noop
 	},
 	method: 'GET',
+	page: null,
 	postData: null,
 	rootElement: null,
 	rules: [],

test/unit/issue/535.test.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const assert = require('proclaim');
+const mockery = require('mockery');
+const extend = require('node.extend');
+const sinon = require('sinon');
+
+
+/**
+ * Note: this test is designed to replicate issue 535
+ *
+ * When setting a default of `ignoreUrl: true`, the `pa11y()` function shouldn't
+ * require a url parameter
+ *
+ * https://github.com/pa11y/pa11y/issues/535
+ */
+describe('lib/pa11y', () => {
+	let pa11y;
+	let pa11yResults;
+	let puppeteer;
+
+	beforeEach(() => {
+
+		pa11yResults = {
+			mockResults: true
+		};
+		/* eslint-disable no-underscore-dangle */
+		global.window = {
+			__pa11y: {
+				run: sinon.stub().returns(pa11yResults)
+			}
+		};
+		/* eslint-enable no-underscore-dangle */
+
+		puppeteer = require('../mock/puppeteer.mock');
+		mockery.registerMock('puppeteer', puppeteer);
+
+		puppeteer.mockPage.evaluate.resolves(pa11yResults);
+
+		pa11y = require('../../../lib/pa11y');
+
+	});
+
+	afterEach(() => {
+		/* eslint-disable no-underscore-dangle */
+		delete global.window;
+		/* eslint-enable no-underscore-dangle */
+	});
+
+	describe('Issue #535', () => {
+		let page;
+		let pa11yError;
+
+		beforeEach(async () => {
+			puppeteer.launch.resetHistory();
+			puppeteer.mockBrowser.newPage.resetHistory();
+			puppeteer.mockBrowser.close.resetHistory();
+			puppeteer.mockPage.close.resetHistory();
+			puppeteer.mockPage.goto.resetHistory();
+
+			page = puppeteer.mockPage;
+
+			pa11y.defaults = extend({}, pa11y.defaults, {
+				browser: puppeteer.mockBrowser,
+				page,
+				ignoreUrl: true
+			});
+
+			try {
+				await pa11y();
+			} catch (error) {
+				pa11yError = error;
+			}
+		});
+
+		it('ignoring url in defaults does not throw error', () => {
+			assert.isNotInstanceOf(pa11yError, Error);
+			assert.notCalled(page.goto);
+		});
+	});
+
+});

test/unit/lib/pa11y.test.js

@@ -86,6 +86,60 @@ describe('lib/pa11y', () => {
 		assert.isFunction(pa11y);
 	});
 
+	describe('pa11y', () => {
+		beforeEach(() => {
+			puppeteer.launch.resetHistory();
+			puppeteer.mockBrowser.newPage.resetHistory();
+			puppeteer.mockBrowser.close.resetHistory();
+			puppeteer.mockPage.close.resetHistory();
+			puppeteer.mockPage.goto.resetHistory();
+		});
+
+		it('throws error when called without a url and `defaults.ignoreUrl` is not defined', async () => {
+			let pa11yError;
+
+			pa11y.defaults = extend({}, pa11y.defaults, {
+				browser: puppeteer.mockBrowser,
+				page: puppeteer.mockPage
+			});
+
+			try {
+				await pa11y();
+			} catch (error) {
+				pa11yError = error;
+			}
+
+			assert.instanceOf(pa11yError, Error);
+			assert.strictEqual(pa11yError.message, 'A url must be defined via the `url` parameter or `options.url`, or `options.ignoreUrl` must be set to true.');
+		});
+
+		it('does not call page.goto when `defaults.ignoreUrl` is set to true', async () => {
+			const page = puppeteer.mockPage;
+
+			pa11y.defaults = extend({}, pa11y.defaults, {
+				browser: puppeteer.mockBrowser,
+				page: puppeteer.mockPage,
+				ignoreUrl: true
+			});
+
+			await pa11y();
+
+			assert.notCalled(page.goto);
+		});
+
+		it('does not call page.goto when `options.ignoreUrl` is set to true', async () => {
+			const page = puppeteer.mockPage;
+
+			await pa11y({
+				browser: puppeteer.mockBrowser,
+				page: puppeteer.mockPage,
+				ignoreUrl: true
+			});
+
+			assert.notCalled(page.goto);
+		});
+	});
+
 	describe('pa11y(url)', () => {
 		let resolvedValue;
 
@@ -1021,6 +1075,10 @@ describe('lib/pa11y', () => {
 			assert.deepEqual(pa11y.defaults.method, 'GET');
 		});
 
+		it('has a `page` property', () => {
+			assert.isNull(pa11y.defaults.page);
+		});
+
 		it('has a `postData` property', () => {
 			assert.isNull(pa11y.defaults.postData);
 		});