README.md

Form troubleshooter

A Chrome extension to find and fix common form problems.

Installation

This extension is be available from the Chrome Web Store.

You can also download the source code for the extension and build and install it locally.

Build from source

You will need Node.js 12 or later to build the extension.

1. Download the code or clone the repo:
   
   git clone [email protected]:GoogleChromeLabs/form-troubleshooter.git
   
   
2. Install dependencies: npm install
3. Build the extension: npm run build

Install the extension locally

1. In Chrome, navigate to chrome://extensions
   
   

2. Enable Developer mode

3. Click the Load unpacked button and select the extension's folder:

   • If you downloaded form-troubleshooter-extension.zip, the extension's folder will be the location of the extracted folder.
   • If you built the extension from source, the extension's folder will be the build/ folder of the repository.

4. You can pin the extension so its icon is always visible: from the Chrome Extensions menu, select Form Troubleshooter
   
   

Usage

Visit a page you want to check, then click the extension icon. The extension retrieves and audits form elements and attributes every time the icon is clicked.

The extension popup has three sections:

• Recommendations
• Common mistakes
• Form details

Save as HTML saves the report as a local HTML file.

You can try out the extension on the test page form-problems.glitch.me.

Development

To develop and test the extension locally, first follow the steps to build from source.

Local web server

Run the local web server with Hot Module Reloading (HMR):

npm run dev

Open http://localhost:8080/.

Note that developing in this mode requires you to bring your own form data. This can be achieved by referencing one of the existing data files in the test-data folder using the data query string parameter:

• http://localhost:8080/?data=/test-data/form-problems.json
• http://localhost:8080/?data=/test-data/score.json
• http://localhost:8080/?data=/test-data/shadow-dom.json

Or by loading a saved form file from the more menu in the top right of the popup.

Running tests

# one off test run
npm run test

# continuously watch for changes
npm run test:watch

Linting

Before contributing any code, make sure that code has been linted.

npm run lint

# reformat files automatically
npm run pretty

Caveats

• The extension is designed to be used as a tool, not to confirm whether code is 'right' or 'wrong'. Form usage is often complex (especially for high-traffic sites) so it's difficult to provide form code validation that is appropriate across a variety of sites.
• Some errors found by the extension may represent known problems, or be triggered by 'incorrect' code that is justified for reasons outside the scope of the extension. In particular, many high-traffic sites use form code in a variety of ways to function at scale and integrate with legacy and third-party systems. The same code may not be appropriate for smaller-scale sites.

However, please provide feedback or file a bug for audit results that appear to be incorrect.

How it works

The extension checks the current page for form and form field elements each time it's opened.

1. The extension icon is clicked to open popup.html.
2. popup.js sends a message to content-script.js that the popup has opened (popup opened).
3. content-script.js traverses the DOM including the shadow DOM and iframes.
4. content-script.js stores a DOM representation using chrome.storage which will be used by content-script.js.
5. content-script.js sends a message via background.js that the DOM has been inspected (dom inspected).
6. content-script.js stores form data using chrome.storage.
7. content-script.js sends a message that element data has been stored (stored element data).
8. On receiving the message, popup.js gets the data from chrome.storage.
9. popup.js runs the audits defined in audits.js, to check the form elements and attributes in the page.
10. popup.js displays an overview of form and form field data in popup.html.
11. popup.js displays results of the audits in popup.html.

Feedback and feature requests

Feedback and audit suggestions welcome!

• Make a comment or request
• File a bug

TODO

• Link to and/or highlight problematic elements.
  • Link to items in the regular DOM.
  • Link to items in shadow DOM.
  • Link to items in iframes.
• Move code for displaying audit results out of audits.js.
• Move constants to external file.
• Check for forms (or other elements) that don't have a closing tag.
• Check for invalid type attribute values, for example <input type="check">.
• Suggest alternatives to invalid attribute names, e.g. for autcomplete.

---

This is not a Google product.