fix(instantsearch): update usage errors (#3543)

Author: francoischalifour

src/lib/InstantSearch.js

@@ -8,6 +8,11 @@ import simpleMapping from './stateMappings/simple';
 import historyRouter from './routers/history';
 import version from './version';
 import createHelpers from './createHelpers';
+import { createDocumentationMessageGenerator } from './utils';
+
+const withUsage = createDocumentationMessageGenerator({
+  name: 'instantsearch',
+});
 
 const ROUTING_DEFAULT_OPTIONS = {
   stateMapping: simpleMapping(),
@@ -47,22 +52,27 @@ class InstantSearch extends EventEmitter {
       searchClient = null,
     } = options;
 
-    if (indexName === null || searchClient === null) {
-      throw new Error(`Usage: instantsearch({
-  indexName: 'indexName',
-  searchClient: algoliasearch('appId', 'apiKey')
-});`);
+    if (indexName === null) {
+      throw new Error(withUsage('The `indexName` option is required.'));
+    }
+
+    if (searchClient === null) {
+      throw new Error(withUsage('The `searchClient` option is required.'));
     }
 
     if (typeof options.urlSync !== 'undefined') {
       throw new Error(
-        'InstantSearch.js V3: `urlSync` option has been removed. You can now use the new `routing` option'
+        withUsage(
+          'The `urlSync` option was removed in InstantSearch.js 3. You may want to use the `routing` option.'
+        )
       );
     }
 
     if (typeof searchClient.search !== 'function') {
       throw new Error(
-        'The search client must implement a `search(requests)` method.'
+        `The \`searchClient\` must implement a \`search\` method.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/backend-instantsearch/js/`
       );
     }
 
@@ -117,7 +127,9 @@ class InstantSearch extends EventEmitter {
   addWidgets(widgets) {
     if (!Array.isArray(widgets)) {
       throw new Error(
-        'You need to provide an array of widgets or call `addWidget()`'
+        withUsage(
+          'The `addWidgets` method expects an array of widgets. Please use `addWidget`.'
+        )
       );
     }
 
@@ -130,7 +142,9 @@ class InstantSearch extends EventEmitter {
     widgets.forEach(widget => {
       // Add the widget to the list of widget
       if (widget.render === undefined && widget.init === undefined) {
-        throw new Error('Widget definition missing render or init method');
+        throw new Error(`The widget definition expects a \`render\` and/or an \`init\` method.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/widgets/create-your-own-widgets/js/`);
       }
 
       this.widgets.push(widget);
@@ -185,7 +199,9 @@ class InstantSearch extends EventEmitter {
   removeWidgets(widgets) {
     if (!Array.isArray(widgets)) {
       throw new Error(
-        'You need to provide an array of widgets or call `removeWidget()`'
+        withUsage(
+          'The `removeWidgets` method expects an array of widgets. Please use `removeWidget`.'
+        )
       );
     }
 
@@ -195,7 +211,9 @@ class InstantSearch extends EventEmitter {
         typeof widget.dispose !== 'function'
       ) {
         throw new Error(
-          'The widget you tried to remove does not implement the dispose method, therefore it is not possible to remove this widget'
+          `The \`dispose\` method is required to remove the widget.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/widgets/create-your-own-widgets/js/#the-widget-lifecycle-and-api`
         );
       }
 
@@ -249,7 +267,11 @@ class InstantSearch extends EventEmitter {
    * @return {undefined} Does not return anything
    */
   start() {
-    if (this.started) throw new Error('start() has been already called once');
+    if (this.started) {
+      throw new Error(
+        withUsage('The `start` method has already been called once.')
+      );
+    }
 
     let searchParametersFromUrl;
 
@@ -349,7 +371,9 @@ class InstantSearch extends EventEmitter {
 
   createURL(params) {
     if (!this._createURL) {
-      throw new Error('You need to call start() before calling createURL()');
+      throw new Error(
+        'The `start` method needs to be called before `createURL`.'
+      );
     }
     return this._createURL(this.helper.state.setQueryParameters(params));
   }

src/lib/__tests__/InstantSearch-test.js

@@ -16,6 +16,125 @@ jest.mock('algoliasearch-helper', () => {
   });
 });
 
+describe('Usage', () => {
+  it('throws without indexName', () => {
+    expect(() => {
+      // eslint-disable-next-line no-new
+      new InstantSearch({ indexName: undefined });
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`indexName\` option is required.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/"
+`);
+  });
+
+  it('throws without searchClient', () => {
+    expect(() => {
+      // eslint-disable-next-line no-new
+      new InstantSearch({ indexName: 'indexName', searchClient: undefined });
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`searchClient\` option is required.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/"
+`);
+  });
+
+  it('throws if searchClient does not implement a search method', () => {
+    expect(() => {
+      // eslint-disable-next-line no-new
+      new InstantSearch({ indexName: 'indexName', searchClient: {} });
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`searchClient\` must implement a \`search\` method.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/backend-instantsearch/js/"
+`);
+  });
+
+  it('throws if addWidgets is called with a single widget', () => {
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.addWidgets({});
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`addWidgets\` method expects an array of widgets. Please use \`addWidget\`.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/"
+`);
+  });
+
+  it('throws if a widget without render or init method is added', () => {
+    const widgets = [{ render: undefined, init: undefined }];
+
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.addWidgets(widgets);
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The widget definition expects a \`render\` and/or an \`init\` method.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/widgets/create-your-own-widgets/js/"
+`);
+  });
+
+  it('does not throw with a widget having a init method', () => {
+    const widgets = [{ init: () => {} }];
+
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.addWidgets(widgets);
+    }).not.toThrow();
+  });
+
+  it('does not throw with a widget having a render method', () => {
+    const widgets = [{ render: () => {} }];
+
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.addWidgets(widgets);
+    }).not.toThrow();
+  });
+
+  it('throws if removeWidgets is called with a single widget', () => {
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.removeWidgets({});
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`removeWidgets\` method expects an array of widgets. Please use \`removeWidget\`.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/"
+`);
+  });
+
+  it('throws if a widget without dispose method is removed', () => {
+    const widgets = [{ init: () => {}, render: () => {}, dispose: undefined }];
+
+    expect(() => {
+      const search = new InstantSearch({
+        indexName: 'indexName',
+        searchClient: { search: () => {} },
+      });
+      search.removeWidgets(widgets);
+    }).toThrowErrorMatchingInlineSnapshot(`
+"The \`dispose\` method is required to remove the widget.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/widgets/create-your-own-widgets/js/#the-widget-lifecycle-and-api"
+`);
+  });
+});
+
 describe('InstantSearch lifecycle', () => {
   let algoliasearch;
   let client;
@@ -67,20 +186,6 @@ describe('InstantSearch lifecycle', () => {
     expect(algoliaSearchHelper).not.toHaveBeenCalled();
   });
 
-  describe('when adding a widget without render and init', () => {
-    let widget;
-
-    beforeEach(() => {
-      widget = {};
-    });
-
-    it('throw an error', () => {
-      expect(() => {
-        search.addWidget(widget);
-      }).toThrow('Widget definition missing render or init method');
-    });
-  });
-
   it('does not fail when passing same references inside multiple searchParameters props', () => {
     const disjunctiveFacetsRefinements = { fruits: ['apple'] };
     const facetsRefinements = disjunctiveFacetsRefinements;
@@ -663,7 +768,9 @@ it('Does not allow to start twice', () => {
   expect(() => instance.start()).not.toThrow();
   expect(() => {
     instance.start();
-  }).toThrowErrorMatchingInlineSnapshot(
-    `"start() has been already called once"`
-  );
+  }).toThrowErrorMatchingInlineSnapshot(`
+"The \`start\` method has already been called once.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/"
+`);
 });

src/lib/__tests__/__snapshots__/search-client-test.js.snap

@@ -28,4 +28,8 @@ Array [
 ]
 `;
 
-exports[`InstantSearch Search Client Properties throws if no \`search()\` method 1`] = `"The search client must implement a \`search(requests)\` method."`;
+exports[`InstantSearch Search Client Properties throws if no \`search()\` method 1`] = `
+"The \`searchClient\` must implement a \`search\` method.
+
+See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/backend-instantsearch/js/"
+`;