CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>WAVE Stand-alone API Documentation</title> <script type="text/javascript" src="/js/index.js"></script> <link rel="stylesheet" href="/styles/index.css?ver=3.2" type="text/css"> <link rel="shortcut icon" href="/favicon.ico"> </head> <body> <header> <nav> <ul> <li><a href="/extension">Browser Extensions</a></li> <li><a href="/standalone">Stand-alone API/Testing Engine</a></li> <li><a href="/api">Subscription API</a></li> <li><a href="/aim">AIM Report</a></li> <li><a href="/help">Help</a></li> </ul> <a href="/"><img src="/img/wavelogo.svg" alt="WAVE Web Accessibility Evaluation Tool" height="120"></a> </nav> <div id="main_form" class="controls"> <form id="waveform" novalidate> <label for="input_url">Web page address:</label><br><input id="input_url" type="url" class="control url"><input class="control" type="submit" id="button_wave" value="WAVE"> </form> </div> </header> <main> <span style="float:right;"> <a href="/api/register">Register</a> |  <a href="/api/login">Login</a> </span> <div style="clear:both;"></div> <h1>WAVE Stand-alone API Documentation</h1> <h2>System Requirements</h2> <ul> <li>Apache or Nginx web server (Ubuntu on Amazon AWS is highly recommended)</li> <li>PHP</li> </ul> <h2>Installation</h2> <p>Extract all API package files, then upload or transfer to your web server. The files in the 'htdocs' directory must be accessible via the web server. If necessary, set up an Apache or Nginx site or virtual directory to point to the directory that contains request.php, or place these files in an existing web director. The 'core' directory should not be publicly accessible and must contain the Puppeteer library (see below).</p> <h3>Installing Puppeteer</h3> <p>The WAVE API requires the <a href="https://github.com/GoogleChrome/puppeteer">Puppeteer Node library</a>.</p> <p>To install Puppeteer, run the following in the API's "/core/" directory:<br> <code>npm i puppeteer</code></p> <p>You may need to <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm">install Node.js and npm first. Node v7.6.0 or greater is required.</a> For Linux, it's best to <a href="https://github.com/nodesource/distributions">use a NodeSource installer</a>.</p> <p>Depending on your operating system, you likely will need to install dependencies for the Chromium browser to run. <a href="https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md">Read details on finding and installing Chromium dependencies.</a> On Debian/Ubuntu, the following command should install all required dependencies:<br> <code>sudo apt-get install gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget</code></p> <p><a href="https://medium.com/mockingbot/run-puppeteer-chrome-headless-on-ec2-amazon-linux-ami-6c9c6a17bee6">For Amazon EC2 Linux AMI, read these instructions.</a></p> <p>If you are exclusively using the browserless.io service, you can instead install Puppeteer-core, which does not include the Chromium browser:<br> <code>npm i puppeteer-core</code></p> <h3>Configuring the WAVE Stand-alone API</h3> <ul> <li>Set permissions to give the web server write permissions on the following: <ul> <li>The /temp/results and /temp/screenshots directories.</li> <li>The /core/api.config.json file. This file stores license information and must not be manually edited.</li> </ul> </li> <li>Open htdocs/user.config.json and set the following: <ul> <li>core_path: Full path of the directory containing the core files (Core.php, etc.). <ul> <li>Always end with a training slash. If on Windows, the path might be something like “D:/website/core/” (use / not \ for slashes).</li> </ul> </li> <li>temp_path: Full path of the /temp/ folder (ending with a training slash) on your server. <ul> <li>If on Windows, the path might be something like “D:/website/temp/” (use / not \ for slashes).</li> </ul> </li> <li>screenshot: true or false. <ul> <li>If set to true, a screenshot will be written to the temp/screenshots/ directory for each page evaluated. Screenshots require up to 1 second to process, are in PNG format, and may be up to megabytes in size. The file name is a random string that, if enabled, will be returned as a “screenshotid” parameter with the API results. These screenshot files will accumulate very quickly, so be careful. This parameter can be set on each request by appending the <i>screenshot</i> GET parameter (e.g., &screenshot=true).</li> </ul> </li> <li>evaldelay: 250 <ul> <li>The number of milliseconds to wait after the last page request before evaluating the page. For very dynamic pages or pages that use React, XHR/AJAX, etc. to load page content after the initial page is rendered, a longer delay will better ensure all page content is fully rendered before WAVE analysis occurs. By default, the API will wait 250 milliseconds after the page has loaded AND after the last request/receive has completed before beginning its analysis. This value can be modified in the config or the <i>evaldelay</i> GET parameter (e.g., &evaldelay=1000) to either increase it for very dynamic pages or pages loading dynamic content from slow sources, or to decrease it for static pages.</li> </ul> </li> <li>viewportwidth: 1200 <ul> <li>The pixel width for the browser window in which the page will be evaluated. This can be handy for testing CSS styles applied at different breakpoints for responsive designs. It also defines the width for screenshots, if enabled above. The default is 1200. Refrain from extremely high values as it may impact speed. This parameter can be set on each request by appending the <i>viewportwidth</i> GET parameter (e.g., &viewportwidth=800).</li> </ul> </li> <li>browserlesskey: "<i>string</i>". <ul> <li>If using the browserless.io service, enter your browserless API key here.</li> </ul> </li> <li>useragent: "<i>string</i>". <ul> <li>By default, the API uses a browser user agent string for a modern Chrome browser on Mac. This can be overridden here. Be sure to use <a href="https://deviceatlas.com/blog/list-of-user-agent-strings">a valid user agent string</a>. This parameter can be set on each request by appending the <i>useragent</i> GET parameter (e.g., &useragent=Mozilla/5.0 (iPhone; CPU...).</li> </ul> </li> <li>savedom: true or false. <ul> <li>If set to true, the rendered page DOM will be saved to the /temp/results/ folder with a random, generated filename (e.g., 73d84f75ce0b8938085d34b583209224.htm). The API will also return a <i>domid</i> value that is the generated value within the filename. This can be used to reference the correct, saved DOM file. The DOM files are not automatically deleted, so may accumulate quickly. The savedom parameter can be set on each request by appending the <i>savedom</i> GET parameter (e.g., &savedom=true).</li> </ul> </li> <li>debug: true or false. <ul> <li>If set to true, debug information will be written to the output screen (this will typically NOT be properly formed JSON) and internal processing results (/temp/results/) will NOT automatically be removed. This can be useful for debugging evaluation failures or server and API configuration errors. This parameter can be set on each request by appending the <i>debug=true</i> GET parameter.</li> </ul> </li> <li>domains: [domainslist]. <ul> <li>The value is a list of domains available for analysis <em>as defined by your WAVE license agreement</em>. The structure is in JSON format. For example, <i>domains: ["webaim.org","w3.org"]</i> - would allow processing of only these two domains. Even if your license allows unlimited domain analysis, you may choose to define these values to ensure proper usage of your API installation.</li> </ul> </li> </ul> </li> <li>Test the API <ul> <li>Simply go to http://YOURSITE.COM/request.php?key=YOURKEY&url=YOURURL (modify the path as needed to access your request.php file).</li> </ul> </li> </ul> <h2>API Query and Output Parameters</h2> <p>See <a href="/api/details">https://wave.webaim.org/api/details</a> for all parameters and API usage details (you will, of course, need to modify URLs to point to your local installation). Additionally, the stand-alone API allows you to pass additional parameters as defined above. If set, these will override any parameters set in the user.config.json file.</p> <h2>API Documentation and Objects</h2> <p>The WAVE Documentation API may be freely accessed via the public WAVE website as documented at <a href="/api/details#documentation">https://wave.webaim.org/api/details#documentation</a>. A JSON object for all WAVE items (including documentation) for use within your application can be provided upon request.</p> <h2>Pre-load and Post-load Scripts</h2> <p>Puppeteer scripts can be run before and after the page to be evaluated is loaded and rendered. Pre-load scripts allow you to perform processes such as logging in to a web site or setting cookies or local storage data (perhaps with session information) - useful if the page to be evaluated requires authentication (complex authentication, such as two-factor, may not work directly). Post-load scripts allow you to manipulate page content, fill out forms, trigger error messages, trigger Single Page App state changes, etc. before the page is analyzed by WAVE.</p> <p>Scripts must be saved in the /temp/scripts/ directory with .js extension. The script template must be formatted as follows:</p> <p><code>module.exports = async (page) => {<br>  <i>YOUR PUPPETEER COMMANDS HERE</i><br>  return page;<br> };</code></p> <p>To run pre- or post-load scripts, append the <code>prescript</code> and/or <code>postscript</code> GET parameters to your API request - <i>request.php?key=YOURKEY&url=YOURURL<strong>&prescript=mypreloadscript.js&postscript=mypostloadscript.js</strong></i></p> <p>IMPORTANT: Because Puppeteer scripts give full control to the Chromium browser within the API, care is in order to ensure that access is limited.</p> <p>Many examples of Puppeteer scripts are available at <a href="https://github.com/checkly/puppeteer-examples">https://github.com/checkly/puppeteer-examples</a>. You can record page interactions using the <a href="https://chrome.google.com/webstore/detail/puppeteer-recorder/djeegiggegleadkkbgopoonhjimgehda?hl=en">Puppeteer Recorder Chrome extension</a>.</p> <p><strong>DO NOT</strong> include high-level Puppeteer commands, such as <code>async</code>, <code>const puppeteer = require('puppeteer');</code>, <code>const browser</code>, <code>const page</code>, <code>await browser.close()</code>, etc. - these are handled by the API already. Pre-load scripts will typically begin with a <code>page.goto</code> to open a page (such as a log-in page). Post-load scripts will NOT include <code>page.goto</code>, but will manipulate the content of or interact with the page being evaluated. Element selectors (found using Puppeteer Recorder or Developer Tools) are used to identify components within the page.</p> <h3>Prescript for logging into a web site</h3> <p><pre><code>module.exports = async (page) => { await page.goto('https://mysite.com/login'); await page.waitFor('#username'); await page.type('#username', 'MyUsername'); await page.waitFor('#password'); await page.type('#password', 'MyP@55word'); await page.click('.login-button'); await page.waitForSelector('#maincontent'); return page; };</code></pre></p> <p>This prescript loads the login page, ensures that the the username and password fields are available, types the username and password into the appropriate fields, clicks the log in button (<code>class="login-button"</code>), and then waits for the <code>"id=maincontent"</code> element to be loaded in the resulting page. The page to be evaluated will be loaded with the authentication and cookies in place.</p> <h3>Prescript for setting site cookie</h3> <p>For sites that rely on cookies to verify authentication information, you can capture the cookie values via Developer Tools or by the EditThisCookie browser extension, then set this cookie data in a prescript.</p> <p><pre><code>module.exports = async (page) => { const cookie = { "domain": "webaim.org", "hostOnly": true, "httpOnly": false, "name": "sessionid", "path": "/", "sameSite": "no_restriction", "secure": false, "session": true, "storeId": "0", "value": "01234567890", "id": 1 } await page.setCookie(cookie) return page; };</code></pre></p> <p>With the sessionid cookie in place, you can then evaluate pages on the site that would otherwise require separate authentication.</p> <h3>Prescript for setting Local Storage session data</h3> <p>Some sites use Local Storage, rather than cookies, to store authentication data. This can also be captured and injected before the page is evaluated.</p> <p><pre><code>module.exports = async (page) => { let json ={"currentUser":"{\"username\":\"username@domain.org\",\"token\":\"eyJ0eXAiOiJKV1QiLCJhbGciOi\"}"}; await page.evaluateOnNewDocument(json => { localStorage.clear(); for (let key in json) localStorage.setItem(key, json[key]); }, json); return page; };</code></pre></p> <p>With a session data in place, you can then evaluate pages on the site that would otherwise require authentication.</p> <h3>Postscript for manipulating page content</h3> <p><pre><code>module.exports = async (page) => { await page.waitFor('#search'); await page.type('#search', 'John'); await page.click('#search-button'); await page.waitFor('#search-results'); await page.click('#search-results > div > .details:nth-child(4)'); await page.waitFor(1000); return page; }; </code></pre></p> <p>This Puppeteer script will wait for the <code>id="search"</code> input element, enter the word "John" into this field, click the search button, wait for the search results element, then click the 4th button (within class="details"), then wait 1000 milliseconds for the details dialog to appear. After the post-script has completed, the API will wait <i>evaldelay</i> milliseconds (default 250) before analyzing the page.</p> <p>Scripts are currently experimental! They may significantly increase API processing time and may result in errors, especially if the page content is lost before or is changing during the API analysis. You can check for internal errors by appending the <i>?debug=true</i> GET parameter to your request, or can save a screen shot to /temp/screenshots/temp.png at any point during the script process with the following Puppeteer script command:<br> <code>await page.screenshot({path: wave.api.config['temp_path'] + "screenshots/temp.png", fullPage: true});</code> </p> <h2>Terms of Use</h2> <p>By licensing the WAVE Accessibility Tool stand-alone online web service, API, and/or related systems (hereafter referred to as WAVE), you acknowledge that you have read, understood, and agree to be bound by the WAVE Terms of Use for your license.</p> </main> <footer> <div class="footerblock"><a href="https://usu.edu/"><img src="/img/web/usu-logo.svg" alt="Utah State University" style="width:70%";></a></div> <div class="footerblock middle"><a href="https://webaim.org/"><img src="/img/web/WebAIM-logo.svg" alt="WebAIM - Web Accessibility in Mind"></a><br> Utah State University<br> 6807 Old Main Hill<br> Logan, UT 84322-6807<br> 435.797.7024</div> <div class="footerblock" id="footerlinks"> <ul> <li id="contact"><a href="/feedback">Contact Us</a></li> <li id="sitewide"><a href="/sitewide">Site-wide WAVE Tools</a></li> <li id="about"><a href="/about">About</a></li> <li id="terms"><a href="/terms">Terms of Use</a></li> </ul> </div> <div id="copyright"> WAVE is © and ® 2025 </div> </footer> </body> </html>