24 | 2. Install dependencies: `npm install`
25 | 3. Build the extension: `npm run build`
26 |
27 | ### Install the extension locally
28 |
29 | 1. In Chrome, navigate to `chrome://extensions`
30 |
31 | 2. Enable **Developer mode**
32 | 3. Click the **Load unpacked** button and select the extension's folder:
33 |
34 | - If you downloaded `form-troubleshooter-extension.zip`, the extension's folder will be the location of the extracted
35 | folder.
36 | - If you built the extension from source, the extension's folder will be the `build/` folder of the repository.
37 |
38 | 4. You can pin the extension so its icon is always visible: from the Chrome **Extensions** menu, select **Form
39 | Troubleshooter**
40 |
41 |
42 | ## Usage
43 |
44 | Visit a page you want to check, then click the extension icon. The extension retrieves and audits form elements and
45 | attributes every time the icon is clicked.
46 |
47 | The extension popup has three sections:
48 |
49 | - **Recommendations**
50 | - **Common mistakes**
51 | - **Form details**
52 |
53 | **Save as HTML** saves the report as a local HTML file.
54 |
55 | You can try out the extension on the test page [form-problems.glitch.me](https://form-problems.glitch.me).
56 |
57 | ## Development
58 |
59 | To develop and test the extension locally, first follow the steps to [build from source](#building-from-source).
60 |
61 | ### Local web server
62 |
63 | Run the local web server with Hot Module Reloading (HMR):
64 |
65 | ```sh
66 | npm run dev
67 | ```
68 |
69 | Open http://localhost:8080/.
70 |
71 | Note that developing in this mode requires you to bring your own form data. This can be achieved by referencing one of
72 | the existing data files in the `test-data` folder using the `data` query string parameter:
73 |
74 | - http://localhost:8080/?data=/test-data/form-problems.json
75 | - http://localhost:8080/?data=/test-data/score.json
76 | - http://localhost:8080/?data=/test-data/shadow-dom.json
77 |
78 | Or by loading a saved form file from the more menu in the top right of the popup.
79 |
80 | ### Running tests
81 |
82 | ```sh
83 | # one off test run
84 | npm run test
85 |
86 | # continuously watch for changes
87 | npm run test:watch
88 | ```
89 |
90 | ### Linting
91 |
92 | Before contributing any code, make sure that code has been linted.
93 |
94 | ```sh
95 | npm run lint
96 |
97 | # reformat files automatically
98 | npm run pretty
99 | ```
100 |
101 | ## Caveats
102 |
103 | - The extension is designed to be used as a tool, not to confirm whether code is 'right' or 'wrong'. Form usage is often
104 | complex (especially for high-traffic sites) so it's difficult to provide form code validation that is appropriate
105 | across a variety of sites.
106 | - Some errors found by the extension may represent known problems, or be triggered by 'incorrect' code that is justified
107 | for reasons outside the scope of the extension. In particular, many high-traffic sites use form code in a variety of
108 | ways to function at scale and integrate with legacy and third-party systems. The same code may not be appropriate for
109 | smaller-scale sites.
110 |
111 | However, please [provide feedback](https://forms.gle/Sm7DbKfLX3hHNcDp9) or
112 | [file a bug](https://github.com/GoogleChromeLabs/form-troubleshooter/issues/new) for audit results that appear to be
113 | incorrect.
114 |
115 | ## How it works
116 |
117 | The extension checks the current page for form and form field elements each time it's opened.
118 |
119 | 1. The extension icon is clicked to open [popup.html](src/popup.html).
120 | 1. popup.js [sends a message](src/js/popup.js#L36) to [content-script.js](src/js/content-script.js#L15) that the popup
121 | has opened (`popup opened`).
122 | 1. content-script.js [traverses the DOM](src/js/content-script.js#L54) including the shadow DOM and `iframe`s.
123 | 1. content-script.js [stores a DOM representation](src/js/content-script.js#L20) using `chrome.storage` which will be
124 | used by content-script.js.
125 | 1. content-script.js [sends a message](src/js/content-script.js#L22) via background.js that the DOM has been inspected
126 | (`dom inspected`).
127 | 1. content-script.js [stores form data](src/js/content-script.js#L20) using `chrome.storage`.
128 | 1. content-script.js [sends a message](src/js/content-script.js#L22) that element data has been stored
129 | (`stored element data`).
130 | 1. On [receiving the message](src/js/popup.js#L48), popup.js [gets the data from chrome.storage](src/js/popup.js#L51).
131 | 1. popup.js [runs the audits](src/js/popup.js#L111) defined in [audits.js](src/js/audits.js), to check the form elements
132 | and attributes in the page.
133 | 1. popup.js [displays an overview](src/js/popup.js#L114) of form and form field data in popup.html.
134 | 1. popup.js [displays results](src/js/popup.js#L113) of the audits in popup.html.
135 |
136 | ## Feedback and feature requests
137 |
138 | Feedback and audit suggestions welcome!
139 |
140 | - [Make a comment or request](https://forms.gle/Sm7DbKfLX3hHNcDp9)
141 | - [File a bug](https://github.com/GoogleChromeLabs/form-troubleshooter/issues/new)
142 |
143 | ## TODO
144 |
145 | - [x] Link to and/or highlight problematic elements.
146 | - [x] Link to items in the regular DOM.
147 | - [x] Link to items in shadow DOM.
148 | - [x] Link to items in iframes.
149 | - [x] Move code for displaying audit results [out of audits.js](js/audits.js#L59).
150 | - [x] Move constants to external file.
151 | - [ ] Check for forms (or other elements) that don't have a closing tag.
152 | - [x] Check for invalid `type` attribute values, for example ``.
153 | - [x] Suggest alternatives to invalid attribute names, e.g. for `autcomplete`.
154 |
155 | ---
156 |
157 | This is not a Google product.
158 |
--------------------------------------------------------------------------------
/cli/README.md:
--------------------------------------------------------------------------------
1 | # Form troubleshooter command line interface
2 |
3 | This tool is a command line interface for running miscellaneous **Form troubleshooter** tasks.
4 |
5 | ## Usage
6 |
7 | ```sh
8 | form-audit rerun [...saved-html-files]
9 | form-audit extract [...saved-html-files]
10 | ```
11 |
12 | ## Installation
13 |
14 | ```sh
15 | # Make sure that form-troubleshooter has been built, run the following command if required (from the `cli` directory):
16 | # (cd .. && npm install && npm run build)
17 |
18 | # From the `cli` directory, install dependencies:
19 | npm install
20 |
21 | # From the `cli` directory, install the command line alias:
22 | npm install --global .
23 | ```
24 |
--------------------------------------------------------------------------------
/cli/index.js:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env node
2 | /* Copyright 2021 Google LLC.
3 | SPDX-License-Identifier: Apache-2.0 */
4 |
5 | /* eslint-disable camelcase */
6 | /* eslint-disable @typescript-eslint/no-var-requires */
7 | const yargs = require('yargs/yargs');
8 | const fs = require('fs');
9 | const { hideBin } = require('yargs/helpers');
10 |
11 | const { audit } = require('form-troubleshooter');
12 | const { version } = require('./package.json');
13 |
14 | const TREE_REGEXP = /\n\n
31 | 2. Enable **Developer mode**
32 | 3. Click the **Load unpacked** button and select the extension's folder:
33 |
34 | - If you downloaded `form-troubleshooter-extension.zip`, the extension's folder will be the location of the extracted
35 | folder.
36 | - If you built the extension from source, the extension's folder will be the `build/` folder of the repository.
37 |
38 | 4. You can pin the extension so its icon is always visible: from the Chrome **Extensions** menu, select **Form
39 | Troubleshooter**
41 |
42 | ## Usage
43 |
44 | Visit a page you want to check, then click the extension icon. The extension retrieves and audits form elements and
45 | attributes every time the icon is clicked.
46 |
47 | The extension popup has three sections:
48 |
49 | - **Recommendations**
50 | - **Common mistakes**
51 | - **Form details**
52 |
53 | **Save as HTML** saves the report as a local HTML file.
54 |
55 | You can try out the extension on the test page [form-problems.glitch.me](https://form-problems.glitch.me).
56 |
57 | ## Development
58 |
59 | To develop and test the extension locally, first follow the steps to [build from source](#building-from-source).
60 |
61 | ### Local web server
62 |
63 | Run the local web server with Hot Module Reloading (HMR):
64 |
65 | ```sh
66 | npm run dev
67 | ```
68 |
69 | Open http://localhost:8080/.
70 |
71 | Note that developing in this mode requires you to bring your own form data. This can be achieved by referencing one of
72 | the existing data files in the `test-data` folder using the `data` query string parameter:
73 |
74 | - http://localhost:8080/?data=/test-data/form-problems.json
75 | - http://localhost:8080/?data=/test-data/score.json
76 | - http://localhost:8080/?data=/test-data/shadow-dom.json
77 |
78 | Or by loading a saved form file from the more menu in the top right of the popup.
79 |
80 | ### Running tests
81 |
82 | ```sh
83 | # one off test run
84 | npm run test
85 |
86 | # continuously watch for changes
87 | npm run test:watch
88 | ```
89 |
90 | ### Linting
91 |
92 | Before contributing any code, make sure that code has been linted.
93 |
94 | ```sh
95 | npm run lint
96 |
97 | # reformat files automatically
98 | npm run pretty
99 | ```
100 |
101 | ## Caveats
102 |
103 | - The extension is designed to be used as a tool, not to confirm whether code is 'right' or 'wrong'. Form usage is often
104 | complex (especially for high-traffic sites) so it's difficult to provide form code validation that is appropriate
105 | across a variety of sites.
106 | - Some errors found by the extension may represent known problems, or be triggered by 'incorrect' code that is justified
107 | for reasons outside the scope of the extension. In particular, many high-traffic sites use form code in a variety of
108 | ways to function at scale and integrate with legacy and third-party systems. The same code may not be appropriate for
109 | smaller-scale sites.
110 |
111 | However, please [provide feedback](https://forms.gle/Sm7DbKfLX3hHNcDp9) or
112 | [file a bug](https://github.com/GoogleChromeLabs/form-troubleshooter/issues/new) for audit results that appear to be
113 | incorrect.
114 |
115 | ## How it works
116 |
117 | The extension checks the current page for form and form field elements each time it's opened.
118 |
119 | 1. The extension icon is clicked to open [popup.html](src/popup.html).
120 | 1. popup.js [sends a message](src/js/popup.js#L36) to [content-script.js](src/js/content-script.js#L15) that the popup
121 | has opened (`popup opened`).
122 | 1. content-script.js [traverses the DOM](src/js/content-script.js#L54) including the shadow DOM and `iframe`s.
123 | 1. content-script.js [stores a DOM representation](src/js/content-script.js#L20) using `chrome.storage` which will be
124 | used by content-script.js.
125 | 1. content-script.js [sends a message](src/js/content-script.js#L22) via background.js that the DOM has been inspected
126 | (`dom inspected`).
127 | 1. content-script.js [stores form data](src/js/content-script.js#L20) using `chrome.storage`.
128 | 1. content-script.js [sends a message](src/js/content-script.js#L22) that element data has been stored
129 | (`stored element data`).
130 | 1. On [receiving the message](src/js/popup.js#L48), popup.js [gets the data from chrome.storage](src/js/popup.js#L51).
131 | 1. popup.js [runs the audits](src/js/popup.js#L111) defined in [audits.js](src/js/audits.js), to check the form elements
132 | and attributes in the page.
133 | 1. popup.js [displays an overview](src/js/popup.js#L114) of form and form field data in popup.html.
134 | 1. popup.js [displays results](src/js/popup.js#L113) of the audits in popup.html.
135 |
136 | ## Feedback and feature requests
137 |
138 | Feedback and audit suggestions welcome!
139 |
140 | - [Make a comment or request](https://forms.gle/Sm7DbKfLX3hHNcDp9)
141 | - [File a bug](https://github.com/GoogleChromeLabs/form-troubleshooter/issues/new)
142 |
143 | ## TODO
144 |
145 | - [x] Link to and/or highlight problematic elements.
146 | - [x] Link to items in the regular DOM.
147 | - [x] Link to items in shadow DOM.
148 | - [x] Link to items in iframes.
149 | - [x] Move code for displaying audit results [out of audits.js](js/audits.js#L59).
150 | - [x] Move constants to external file.
151 | - [ ] Check for forms (or other elements) that don't have a closing tag.
152 | - [x] Check for invalid `type` attribute values, for example ``.
153 | - [x] Suggest alternatives to invalid attribute names, e.g. for `autcomplete`.
154 |
155 | ---
156 |
157 | This is not a Google product.
158 |
--------------------------------------------------------------------------------
/cli/README.md:
--------------------------------------------------------------------------------
1 | # Form troubleshooter command line interface
2 |
3 | This tool is a command line interface for running miscellaneous **Form troubleshooter** tasks.
4 |
5 | ## Usage
6 |
7 | ```sh
8 | form-audit rerun [...saved-html-files]
9 | form-audit extract [...saved-html-files]
10 | ```
11 |
12 | ## Installation
13 |
14 | ```sh
15 | # Make sure that form-troubleshooter has been built, run the following command if required (from the `cli` directory):
16 | # (cd .. && npm install && npm run build)
17 |
18 | # From the `cli` directory, install dependencies:
19 | npm install
20 |
21 | # From the `cli` directory, install the command line alias:
22 | npm install --global .
23 | ```
24 |
--------------------------------------------------------------------------------
/cli/index.js:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env node
2 | /* Copyright 2021 Google LLC.
3 | SPDX-License-Identifier: Apache-2.0 */
4 |
5 | /* eslint-disable camelcase */
6 | /* eslint-disable @typescript-eslint/no-var-requires */
7 | const yargs = require('yargs/yargs');
8 | const fs = require('fs');
9 | const { hideBin } = require('yargs/helpers');
10 |
11 | const { audit } = require('form-troubleshooter');
12 | const { version } = require('./package.json');
13 |
14 | const TREE_REGEXP = /\n\n