Maintaining high code quality, accessible markup, and secure coding standards across complex web applications requires automated verification directly within the browser engine. While Google Chrome and Microsoft Edge utilise Lighthouse for page health auditing, Safari Web Inspector offers a distinct, highly extensible Audit Tab built directly into WebKit.
In addition to running Apple’s built-in accessibility audit rules, developers can create custom audit test suites using JavaScript and JSON. This functionality allows frontend teams to automatically enforce company design systems, verify mandatory meta tags, detect prohibited third-party scripts, and assert WCAG contrast standards before deploying code to production. This tutorial explains how to navigate the Audit tab, execute built-in accessibility evaluations, and write custom audit test cases in Safari Web Inspector.
Understanding the Safari Audit Tab Architecture
The Audit tab in Safari Web Inspector evaluates live DOM nodes, computed styles, resource timings, and script execution contexts against predefined test assertions. Unlike static linters, Safari audits execute against the rendered, hydrated runtime state of your web page, evaluating client-side JavaScript modifications, shadow DOM elements, and responsive layout shifts.
Audits in Safari Web Inspector are organised into three levels:
- Audit Test: An individual verification rule executing a JavaScript evaluation function that returns a boolean pass/fail status or a collection of offending DOM nodes.
- Audit Category: A logical grouping of related tests (for example, “SEO Requirements”, “Security Headers”, or “ARIA Compliance”).
- Audit Test Suite: An exportable bundle containing multiple categories and tests, saved as an
.auditor JSON file that can be shared across engineering teams.
Step 1: Enable Web Inspector and Access the Audit Tab
- Launch Safari on macOS.
- Ensure developer features are enabled: go to Safari > Settings > Advanced and check Show features for web developers.
- Navigate to the website or local web application you want to audit.
- Open Web Inspector by pressing Cmd + Option + I or right-clicking anywhere on the page and choosing Inspect Element.
- In the Web Inspector toolbar, select the Audit tab (represented by a checklist clipboard icon).
Step 2: Run Built-In WebKit Audits
Safari Web Inspector ships with a comprehensive default test suite: Accessibility.
- In the left sidebar of the Audit tab, select the default Accessibility audit suite.
- Review the included categories, such as Forms, Images, Keyboard, and Links.
- Click the Start Audit button in the top-right corner.
- Web Inspector scans the active page within seconds, categorising findings into Passed, Warnings, and Errors.
- Click on any flagged error (such as “Images must have alternate text”) to expand the failure explanation and view direct links to the offending DOM nodes in the Elements tab.
Step 3: Create a Custom Audit Test Suite
To create custom test rules specific to your project or organisation:
- In the bottom-left corner of the Audit panel sidebar, click the Add (+) button and select New Suite.
- Select your newly created suite in the sidebar and rename it in the right inspector pane (e.g., “Production Readiness Audit”).
- Click the Add (+) button again and select New Test.
- Assign a descriptive name to the test (e.g., “Ensure All Images Define Explicit Dimensions”).
- Set the Severity level (Error, Warning, or Pass/Fail).
Step 4: Author JavaScript Audit Test Logic
Safari audits use an evaluation function executed in the context of the page. Select your custom test and locate the Test Function code editor in the inspector pane.
Example 1: Auditing Missing Image Dimensions
To prevent Cumulative Layout Shift (CLS), all image elements should declare explicit width and height attributes:
function test(result) {
const images = Array.from(document.querySelectorAll('img'));
const missingDimensions = images.filter(img => !img.hasAttribute('width') || !img.hasAttribute('height'));
if (missingDimensions.length === 0) {
return result.pass("All images have explicit width and height attributes.");
}
return result.fail("Images found lacking width or height attributes.", {
nodes: missingDimensions
});
}
Example 2: Auditing Crucial SEO & Viewport Meta Tags
To verify that essential mobile viewport and indexing tags are present:
function test(result) {
const viewport = document.querySelector('meta[name="viewport"]');
const description = document.querySelector('meta[name="description"]');
if (!viewport) {
return result.fail("Missing mobile viewport meta tag.");
}
if (!description || !description.content.trim()) {
return result.fail("Missing or empty meta description tag.");
}
return result.pass("Core viewport and description meta tags are present.");
}
Step 5: Run and Review Custom Audits
- Click Start Audit in the top toolbar to execute your custom test suite against the live DOM.
- Inspect the generated audit report: passing tests are highlighted in green, while failed tests display the custom error message alongside clickable DOM node references passed in the
nodesarray. - Click any referenced node to jump directly to its position in the Elements tree for immediate remediation.
Step 6: Export and Share Audit Test Suites
To standardise quality assurance across multiple developers on your team without manual configuration:
- Right-click your custom audit suite in the left sidebar of the Audit tab.
- Select Export Audit.
- Save the generated JSON file to your project repository (e.g.,
safari-audit-rules.json). - Team members can import the file by opening Safari Web Inspector, clicking the Add (+) button in the Audit tab, selecting Import Audit, and choosing the shared file.