Safari Developer Guide

Safari Web Inspector
Guide
Contents
About Safari Web Inspector 6
At a Glance 7
Get Started 7
Inspect the DOM and Resources 7
Measure and Improve Page Performance 7
Debug JavaScript 7
Interact with the Console 8
How to Use This Document 8
See Also 8
Get Oriented 9
Enabling Web Inspector 9
WebKit-based Apps 10
Safari on iOS 10
Navigating Web Inspector 13
Positioning Web Inspector 14
Changing Toolbar Appearance 15
Reading the Activity Viewer 16
Resources and the DOM 17
Inspecting the DOM 17
Source versus DOM 17
Editing Nodes 19
Style 19
Computed 20
Rules 21
Metrics 22
Layers 23
Node 25
Resource 26
Resources and Storage 27
JavaScript and CSS 27
Storage 28
Extension Scripts 30
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
2
Timelines 31
Recording Timelines 31
Network Requests 32
Layout and Rendering 33
JavaScript and Events 33
Timing Profiles 34
JavaScript Profiling 34
CSS Selector Profiling 35
Debugger 36
Breakpoints 36
Conditional Breakpoints 38
Call Stack 39
Debugger Controls 40
Scope Chain 40
Local Variables 41
Closure Variables 42
Global Variables 42
The Console 43
Command-Line API 43
Console API 45
The Develop Menu 47
Changing the User Agent String 48
Snippet Editor 50
Keyboard Shortcuts 51
Navigation Shortcuts 51
DOM Tree Shortcuts 52
Console Shortcuts 52
Debugger Shortcuts 52
Miscellaneous Shortcuts 53
Document Revision History 54
3
Contents
Figures, Tables, and Listings
Get Oriented 9
Figure 1-1 The Advanced pane of Safaris preferences 9
Figure 1-2 The Web Inspector toolbar item 9
Figure 1-3 The activity viewer 16
Table 1-1 Toolbar icons 13
Table 1-2 Toolbar variants 15
Table 1-3 Buttons in the activity viewer 16
Resources and the DOM 17
Figure 2-1 Spacing properties are color-coded 17
Figure 2-2 Viewing the source code 18
Figure 2-3 Viewing the DOM tree 18
Figure 2-4 The Computed tab in the Style details sidebar 20
Figure 2-5 The Rules tab in the Style details sidebar 21
Figure 2-6 The Metrics tab in the Style details sidebar 22
Figure 2-7 The Layer details sidebar 24
Figure 2-8 The Node details sidebar 25
Figure 2-9 The Resource details sidebar 26
Figure 2-10 Cookies 28
Figure 2-11 The Local Storage resource 28
Timelines 31
Figure 3-1 Network requests in the Timelines navigation sidebar 32
Figure 3-2 Layout and rendering events in the Timelines navigation sidebar 33
Figure 3-3 JavaScript events in the Timelines navigation sidebar 33
Figure 3-4 Profiling JavaScript 34
Figure 3-5 Profiling CSS 35
Debugger 36
Figure 4-1 An active breakpoint on line 17 and an inactive breakpoint on line 19 36
Figure 4-2 All breakpoints are listed in the navigation sidebar 37
Figure 4-3 An active and inactive breakpoint when breakpoints are disabled 37
Figure 4-4 Hovering over a variable inspects the object 38
Figure 4-5 Editing a breakpoint 38
4
Figure 4-6 Setting a conditional breakpoint 39
Figure 4-7 The call stack 39
Figure 4-8 Variables defined within the scope of the immediate function 41
Figure 4-9 Variables available to the current scope outside the immediate function 42
Figure 4-10 Variables in the global scope 42
The Console 43
Table 5-1 Commands available in the Web Inspector console 43
Table 5-2 JavaScript functions available in the Console API 45
Listing 5-1 Find the events attached to this element 44
The Develop Menu 47
Figure A-1 The type and version of various browsers in the User Agent submenu 49
Figure A-2 Snippet Editor can help you isolate problems with your markup 50
5
Figures, Tables, and Listings
Note: This document was formerly titled Safari Developer Tools Guide . It has been updated to
support Safari 6.1.
Web Inspector is an open source web development tool built into Safari that makes it easy to prototype,
optimize, and debug your web content on iOS and OS X.
Read this guide to get started using Web Inspector.
6
About Safari Web Inspector
Note: As a web developer, you are encouraged to live on the bleeding edge. Download the latest
WebKit Nightly, the developmental branch of Safari. It contains experimental, developer-facing
features, so you can try out new WebKit functionality before it reaches wider audiences.
At a Glance
This document is organized by areas of the Web Inspector interface.
Get Started
Learn how to enable and customize the appearance of Web Inspector.
Relevant Chapter: Get Oriented (page 9)
Inspect the DOM and Resources
At the heart of Web Inspector is the ability to inspect the Document Object Model (DOM). Web Inspector shows
you the structure of your DOM as perceived by Safaris rendering engine, WebKit. But the DOM isnt all you
can inspect. External resources and locally stored datasuch as scripts, stylesheets, and offline storagecan
be inspected, providing insight to the data available to your web content.
Relevant Chapter: Resources and the DOM (page 17)
Measure and Improve Page Performance
Web Inspector provides a suite of tools you can use to quantify the speed of your webpages. You can monitor
network requests as they download, observe page layout calculations performed by the WebKit rendering
engine, and profile the efficiency of your JavaScript functions and CSS selectors.
Relevant Chapter: Timelines (page 31)
Debug JavaScript
Turn to Web Inspector when your front-end logic goes awry. Web Inspector offers a debugging environment
that lets you pause script execution and observe the values of your variables as they are defined.
At a Glance
7
Relevant Chapter: Debugger (page 36)
Interact with the Console
Lift up the hood of your webpages and interact directly with your web content in the console.
Relevant Chapter: The Console (page 43)
How to Use This Document
When reading this document, follow along with Web Inspector open in Safari. It is recommended to actively
use Web Inspector on this page while you read about its features for a hands-on learning experience.
See Also
!
WWDC 2013: Getting to Know Web Inspector provides a walkthrough of the Web Inspector UI.
!
WWDC 2013: Getting the Most Out of Web Inspector describes advanced concepts of harnessing the power
of Web Inspector to your advantage.
!
Safari Extensions Development Guide delivers step-by-step directions for creating Safari extensions using
Extension Builder.
!
Safari Extensions Reference lists the JavaScript classes, methods, and properties you can access with Safari
extensions.
!
Safari Web Content Guide offers guidance for developing web content for iOS.
How to Use This Document
8
Before you start using Web Inspector, familiarize yourself with its organization and interface.
Enabling Web Inspector
To start using Web Inspector, you must first enable the Develop menu. To do so, enable the Show Develop
menu in menu bar setting found in Safaris preferences under the Advanced pane, as shown in Figure 1-1.
Figure 1-1 The Advanced pane of Safaris preferences
You can then access Web Inspector through the Develop menu that appears in the menubar, or by pressing
Command-Option-I. You can also add the Web Inspector toolbar item to Safaris toolbar by selecting View >
Customize Toolbar.
Figure 1-2 The Web Inspector toolbar item
9
Get Oriented
WebKit-based Apps
To enable the developer tools in a WebKit-based application other than Safari, enter the following into the
Terminal:
defaults write com.bundle.identifier WebKitDeveloperExtras -bool true
Replace com.bundle.identifier with the bundle identifier of your app, and then launch your app. Web
Inspector can nowbe accessed by a Control-click or right-click fromwithin any web view. You must also enable
contextual menus in your app.
Safari on iOS
You can use Web Inspector to debug web content on your device directly from your desktop.
Note: Web Inspector is available on iOS 6 and later.
To enable Web Inspector on iOS
1. Open the Settings app.
2. Tap Safari.
Get Oriented
10
3. Scroll down and select Advanced.
Get Oriented
11
4. Switch Web Inspector to ON.
After Web Inspector is enabled, connect your device to your desktop machine with a USB cable. The name of
your device appears in the Develop menu of Safari alongside all open inspectable apps and webpages.
Get Oriented
12
Alternately, you can use iOS Simulator to take advantage of Web Inspectors debugging capabilities, which
comes free with Xcode from the Mac App Store. Use the same instructions,To enable Web Inspector on
iOS (page 10), from within the iOS Simulators Settings app.
If you have a development provisioning profile installed on your device, you can even inspect the web content
of any UIWebView object in your app. The name of your app will appear as a submenu under the name of
your device. When debugging web content in a web view, Web Inspector behaves in the same manner as
debugging web content in Safari.
Navigating Web Inspector
The toolbar icons listed in Table 1-1 are in order as they appear in Web Inspector, from left to right.
Table 1-1 Toolbar icons
Described in Name Icon
Resources and the DOM (page 17) Resources navigation sidebar
Timelines (page 31) Timelines navigation sidebar
Debugger (page 36) Debugger navigation sidebar
The Console (page 43) Console
Inspecting the DOM (page 17) Inspect
Scope Chain (page 40) Scope Chain details sidebar
Get Oriented
Navigating Web Inspector
13
Described in Name Icon
Style (page 19) Style details sidebar
Layers (page ?) Layers details sidebar
Node (page 25) Node details sidebar
Resource (page 26) Resource details sidebar
Positioning Web Inspector
There are three positions that Web Inspector can take: docked to the bottom of the window, docked to the
right of the window, or in its own window. When inspecting web content on OS X, Web Inspector is docked
to the bottom of the window by default. You can detach Web Inspector into its own window by pressing the
detach button ( ). This mode is especially advantageous when working on a computer with multiple
displays.
Note: When inspecting web content on iOS, Web Inspector must be in its own window.
When in its own window, Web Inspector presents another button allowing you to dock Web Inspector to the
right of the window. This is particularly useful for inspecting narrow web content on wide monitors. Press the
Dock to Right button ( ) to dock Web Inspector to the right side of the window.
Hold down the Option key to switch docking types.
Get Oriented
Positioning Web Inspector
14
Changing Toolbar Appearance
You can change the look and feel of the toolbar to better suit your liking. Depending on the size of your screen,
you might want to adjust your toolbar to take up less space. Right-clicking anywhere on the toolbar invokes
a contextual menu which allows you to change the layout and size of the toolbar icons.
Possible toolbar appearances are shown in Table 1-2. By default, toolbar icons are presented with icons and
text positioned vertically.
Table 1-2 Toolbar variants
Appearance Para
Icon and Text
(Vertical)
Icon and Text
(Horizontal)
Icon only
Text only
You also have the option to make the icons smaller by selecting Small Icons from the contextual menu.
Get Oriented
Changing Toolbar Appearance
15
Reading the Activity Viewer
The activity viewer is like a heads-up display for the loaded page. It shows an at-a-glance summary of key
information about the current page, as shown in Figure 1-3. Each label in the activity viewer is a button that,
when clicked, takes you to an area of Web Inspector.
Figure 1-3 The activity viewer
Table 1-3 Buttons in the activity viewer
Button action Description Item
Opens the Resources navigation sidebar.
See Resources and the DOM (page 17).
The total number of resources.
Resource
count
Opens the Networks Requests timeline.
See Network Requests (page 32).
The total file size of all resources.
Resource size
Opens the Networks Requests timeline.
See Network Requests (page 32).
The time elapsed until the load
event.
Load time
Opens the console. See The
Console (page 43).
The number of logs printed to
the console.
Logs
Console (page 43).
The number of errors printed to
the console.
Errors
Console (page 43).
The number of warnings printed
to the console.
Warnings
Note: You need to load the webpage with Web Inspector open for values to appear in the activity
viewer.
Get Oriented
Reading the Activity Viewer
16
The Document Object Model (DOM) is the API between your JavaScript and HTML. Each HTML element is
rendered as a node in the DOM tree.
Inspecting the DOM
At the heart of Web Inspector is the ability to inspect, or locate within the DOM tree, a specific element on the
page. After the specific element is selected in the DOM tree, details about the element become available, such
as the elements styles and event listeners.
Click the Inspect button, and start moving your mouse along the page. Notice that the elements you hover
over becomes highlighted in a set of colors, and a tooltip appears, indicating the elements tag and total
dimensions. The colors that appear upon hover represent the elements margin, border, padding, and
dimensions, as illustrated in Figure 2-1.
Figure 2-1 Spacing properties are color-coded
With the Inspect button selected, click on this sentence. You can also right-click on this sentence and select
Inspect Element in the contextual menu. Notice that the corresponding node becomes selected in the content
browser.
Source versus DOM
The notions between a pages source and a pages DOM are similar, but different. The source is the raw HTML
that is unadulterated by any client-side scripts. It is the direct response of the HTTP request to the server. The
DOM, on the other hand, is the same HTML structure that has been modified by JavaScript.
17
Resources and the DOM
Source Code reads the pages HTML as if you opened it in a text editor. The source code reflects your HTML
structure before any JavaScript is loaded. While the contents cant be edited, its useful to see the HTML Safari
receives from the server.
Figure 2-2 Viewing the source code
The DOM tree is fully editable. Of course, your edits are temporary, so any changes you make are lost in a
browser refresh. To save changes you make to the DOMtree, select the root html node and press Command-C,
which copies the DOM structure to you clipboard as HTML.
Figure 2-3 Viewing the DOM tree
You can switch between the pages DOM tree and source code in the Navigation bar.
Inspecting the DOM
18
The Shadow DOM
WebKit automatically inserts HTML in certain elements. For example, the placeholder of text inputs is actually
another HTML element that is hidden within the input itself. These hidden elements are known as the Shadow
DOM. You can enable viewing shadow nodes in the content browser by clicking on the Shadow DOM button
( ).
Editing Nodes
To edit the markup of an element, double-click an element name, attribute name, or attribute value. Alternately,
you can press the Enter key to input a newattribute. You can also use the Tab key and Shift-Tab key combination
to cycle through attributes.
For example, inspect this paragraph and press the Enter key. Youll see a text field appear within the highlighted
node. Type in class="notebox" and press Enter. A blue border appears surrounding the paragraph. Thats
because the notebox class is already defined in the stylesheets included in this page. Deleting the class
attribute or its value restores it to its original appearance.
Rearrange nodes with a simple drag and drop. Delete nodes by pressing the delete key. Try editing a couple
nodes on this pageinspect this paragraph, then drag it above or below other nodes in the DOM tree. Youll
see the order of paragraphs change in the page to reflect the changed order in the DOM tree. All of your
changes are local and wont persist across pageloads. If you want to undo a change without losing other
modifications youve made to the DOM, go to Edit > Undo (Command-Z) to undo your change.
Style
The Style details sidebar shows all of the CSS styles that pertain to the selected element. It also contains a series
of checkboxes representing the elements active, focus, hover, and visited pseudo-state. You can select these
checkboxes to enable the pseudo-state without interacting with the element directly. For example, selecting
the Hover checkbox will change the appearance of the element as if the mouse cursor is hovering over it.
Editing Nodes
19
Computed
The computed styles show all CSS styles associated with the selected element. It shows properties set to this
specific element, as well as properties inherited from other selectors.
Figure 2-4 The Computed tab in the Style details sidebar
The styles displayed in the Computed tab are read-only. To edit an elements styles, go to the Rules (page
21) tab.
Next to every color in the Style sidebar is a color swatch. Clicking on the square swatch cycles through different
formats of expressing that color. You can cycle through Hex, RGB, RGBA, HSL, HSLA, and named color values,
depending on the color in contextfor example, colors without alpha channels wont cycle through RGBA or
HSLA; colors that dont represent an exact named color wont cycle through the named color.
To see every CSS property, click on the Show All checkbox. This shows properties and their default values.
Style
20
Rules
The Rules tab lists CSS rules that pertain to the selected element. The rules are collected from inline styles,
attached stylesheets, and User Agent stylesheets. User Agent stylesheets are styles that Safari itself applies,
such as a default margin.
Here, you can edit your styles as you would in a text editor. As you begin typing, notice that CSS properties
auto-complete. As soon as your rule is valid, the style is automatically applied to the page. You can uncheck
the checkbox that appears next to rules on hover to disable them, or press the Delete key to remove them
entirely.
Figure 2-5 The Rules tab in the Style details sidebar
Style
21
Inspect this paragraph, then click on New Rule. Web Inspector creates a rule with a selector that matches the
selected element. In this case, the element is a paragraph, so Web Inspector chose the generic p tag. Type
color: red; underneath the p selector, and notice that this entire paragraph instantly turns red.
Metrics
The Box Model provides an easy way to visualize the dimensions of an element at a glance. From the center
out, it shows the width and height, padding, border, and margin of the selected node. All of the values are
editable; double-click and type in a value to see the change update immediately. As in the Rules tab, you can
hold the Option key while pressing the up- or down-arrow keys to increment or decrement the current value.
Figure 2-6 The Metrics tab in the Style details sidebar
Inspect this sentence, and then click the Metrics tab. As you move your mouse over areas of the box model,
youll see the corresponding areas on the page flash with color. Give the padding-bottom a value by
double-clicking the hyphen directly underneath the dimensions. Type in a number (50, for example) and press
Enter. Youll notice the padding underneath this paragraph expand by 50 pixels. You do not need to supply a
unit in the box modelall values are in pixels.
Style
22
Adding values in the Metrics tab affects only the selected element. The values are applied as an inline style;
look back in the content browser and notice that the selected node now has a style attribute. If youd like
the style applied to multiple elements, youll need to create a rule in the Rules (page 21) tab that matches
a certain selector.
Layers
The Layer details sidebar provides information about what is composited as a layer. Elements that have a 3D
transform, a fixed position, or overlap other composited elements are rendered in their own layer so that its
movement during animations or scrolling can be hardware-accelerated for maximum performance.
However, each layer increases the memory footprint of your webpage (significantly for layers covering a large
area). You should avoid having elements in their own layer unless absolutely necessary. If your page has poor
scrolling or resizing performance, check to see if any nodes are being repainted on every scroll or resize event.
Layers
23
To see which elements on your page are rendered in their own layer, select the root html node in the content
browser. Any elements composited in a layer appear here, as shown in Layers. Clicking on the row in this
table causes a popover to appear, explaining the reasons for compositing. When possible, minimize the number
of layers present by eliminating the elements need for compositing. Clicking the arrow that appears on hover
jumps to the nodes location in the content browser.
Figure 2-7 The Layer details sidebar
The number of element repaints is displayed next to the node name. A repaint occurs when the rendering
engine assesses that a portion of the pages visual presentation needs updatingfor example, when a hovered
link becomes underlined, or when a window resizes. Repaints are expensive operations that can negatively
affect the responsiveness of your webpage as well as impact the users battery life.
To visualize the pages layers and their repaints, click the Composite Borders button ( ) in the Navigation
bar. Clicking this button outlines each layer with a colored border. Large layers are divided into tiles, which
also become outlined. Whenever a tile repaints, the counter in the tiles upper-left corner increments.
Layers
24
The amount of memory the element consumes is also displayed in the Layer details sidebar. The amount of
memory an element consumes is determined by multiplying the product of the elements dimensions by 4
bytes (1 byte for each red, green, blue, and alpha channel).
Node
The Node sidebar shows information relating to the selected elements prototypal object, as shown in Figure
2-8.
Figure 2-8 The Node details sidebar
The Attributes section lists the names and values of HTML attributes of the selected node. These values are
read-only; to edit an elements attributes, double-click the node in the content browser.
Node
25
The Properties section lists all available methods and properties available to the selected element, including
methods and properties inherited from its parent objects.
The Event Listeners section lists all JavaScript events attached to this node and its ancestors. It presents the
type of event, such as click or mouseover, as well as the name of the function it calls. If your JavaScript events
arent firing as expected, check here to confirm that the element is indeed listening for the intended event
and function.
Resource
The Resource sidebar shows information about the selected resource. You can viewthe full URL of the resource,
as well as the server request and response headers that were sent with this resource, as shown in Figure 2-9.
Figure 2-9 The Resource details sidebar
Resource
26
Resources and Storage
Resources are grouped implicitly. If there are over a certain number of resources on a page, then images, scripts,
stylesheets, fonts, frames, and XHRs (XMLHttpRequests) coalesce into groups. These groups are represented
by a folder. Groups do not reflect directory structure; that is to say, the organization of resources in the sidebar
does not represent the path of the resource.
JavaScript and CSS
External JavaScript and CSS files are expanded by default. You might have minified some resources to reduce
file sizea common practice on the web. Web Inspector automatically expands, or pretty-prints, your minified
code in order to be easier to read. To toggle between pretty-print and original formatting, click the code
formatting button ( ).
If source maps are present, Web Inspector splits production JavaScript and CSS into its original source files.
Concatenated resourcesfor example, ones created by a CSS preprocessor or a build scriptappear as a
group, and the source files are listed as children. The names of source-mapped files appear throughout Web
Inspector in italics; click the file name to jump to the position in the concatenated file, and Command-click the
file name to jump to the position in the original source file.
JavaScript files allow you to set breakpoints in the left margin. To learn more about setting breakpoints, read
Breakpoints (page 36).
While its quicker to change an elements CSS rules in the Figure 2-11 (page 28) sidebar, you can also live-edit
the stylesheet directly in the content browser. Select a CSS resource and begin typing, just as you would in a
text editor.
Note: You must view the CSS file in its original formatting (not pretty-printed) in order to live-edit
a stylesheet.
Changes you make to JavaScript or CSS files can easily be saved onto disk by pressing Command-S. Saving
external resources with Web Inspector allows you to rapidly prototype without the need to switch back to
your text editor.
27
Storage
Cookies
If your website uses cookies, they appear as an offline resource in the Resources navigation sidebar. As shown
in Figure 2-10, cookies are displayed in a table that lists each cookies name, value, domain, path, expiration
date, and size.
Figure 2-10 Cookies
Entries in this table are read-only; if you want to edit a cookies value, you need to do so with the
document.cookie object in JavaScript (you can use the Quick Console at the bottom of the content browser
to modify the cookie and see the results update in real time). Pressing the Delete key while a cookie is selected
deletes the cookie.
Local and Session Storage
If your web app uses HTML5 Web Storage, keys and values you set in your code appear in the Local Storage
offline resource, as shown in Figure 2-11. Local storage is displayed as an editable data grid of key-value pairs.
Double-click an empty row to create a new entry, and double-click an existing entry to edit its value. Pressing
the Delete key on a selected entry removes the key-value pair. Local storage provides a database of up to 5
MB per domain that persists even after Safari is quit.
Figure 2-11 The Local Storage resource
28
Session storage is also displayed as an editable data grid of key-value pairs. Unlike local storage, session storage
persists for as long as the window or tab remains open.
SQL Databases
If your webpage uses Web SQL Databases, they appear as an offline resource under Databases in the Resources
navigation sidebar. Click the Databases disclose triangle to see a list of open databases and their tables. Selecting
a database table displays a data grid containing all the columns and rows for that table.
In addition to inspecting HTML5 databases, you can interact with them by issuing SQL queries against any of
the displayed databases. Select a database in the sidebar to see an interactive console for evaluating SQL
queries.
The input to this console has auto-completion and tab-completion for table names in the database, as well as
common SQL keywords.
29
Application Cache
Websites that provide a manifest file can have items stored in Safaris offline application cache. On subsequent
visits to the website, Safari loads these items from the cache instead of loading them from the website again.
This provides a mechanismfor websites to offer features such as canvas-based games that users can play, even
when their devices browser has no Internet connection.
You can inspect all the current contents of the application cache by clicking Application Cache. Safari shows
a list of domains that have cached files. Select a domain to see the files in that domains cache, showing the
URL from which they were loaded, the type of entry the resource was specified as (explicit, manifest, master,
or fallback), and the file size.
When the Application Cache is selected, the Storage details sidebar is also shown. It reports if the target device
is online or not, and its current status.
Extension Scripts
Any scripts that have loaded from an installed Safari extension appear in a group labeled Extension Scripts.
For more information about Safari Extensions, read Safari Extensions Development Guide .
30
Web Inspector features a visual download analyzer and a JavaScript profiler to help you make your website
load and your scripts run as quickly and responsively as possible.
Recording Timelines
Timelines are a graphical representation of activity that occurs during the lifetime of the open page. Timelines
show network requests, CSS rendering, and JavaScript events.
All timelines record simultaneously. You can start recording timelines two ways:
!
Clicking the Start Recording button. This shows all activity that happens since the record button is clicked.
While recording, you can interact with the page to trigger XHR loads, style recalculation, page layout and
painting, and JavaScript events.
!
Reloading the webpage while Web Inspector is open. This shows all activity as it happens during page
load.
To stop recording, click the Stop Recording button. The content browser shows various details depending on
the selected timeline.
31
Timelines
Network Requests
Figure 3-1 shows recorded network requests as blue horizontal bars.
Figure 3-1 Network requests in the Timelines navigation sidebar
When the Network Requests timeline is selected, the bottom portion of the content browser displays each
individual file requested from the webpage. The horizontal bar graph shows you when each resource was
requested, the latency of the server, and the download time for each resource. Hover over any bar to see
additional details in a tooltip.
The vertical dashed blue line indicates when the DOM becomes available to Safari, and is equivalent to the
DOMContentLoaded JavaScript event. The red line indicates when all resources have finished loading, and is
equivalent to the load JavaScript event.
Timelines
Recording Timelines
32
Layout and Rendering
Just as you can see great detail about every resource that has loaded, you can see great detail about how
Safari's rendering engine, WebKit, renders the page. Click on Layout & Rendering in the Timelines pane to
display a table of each paint that has been rendered, as shown in Figure 3-2. Each layout calculation and paint
rendering is represented by a purple horizontal bar.
Figure 3-2 Layout and rendering events in the Timelines navigation sidebar
JavaScript and Events
JavaScript executed during a recording session is represented as a yellow horizontal bar in the timeline.
Evaluated scripts, dispatched events, animation frames, and timers are listed in the table in the content browser,
as shown in Figure 3-3.
Figure 3-3 JavaScript events in the Timelines navigation sidebar
Timelines
Recording Timelines
33
Timing Profiles
Underneath the Timelines pane in the Timelines navigation sidebar is the Profiles pane. This pane allows you
to see where execution time is being spent in your JavaScript and CSS. Use the Profiles pane to find bottlenecks
in your scripts and inefficiency in your CSS selectors to optimize their performance.
JavaScript Profiling
Profiling JavaScript exposes the bulk of your codes execution time. To use the Profiles pane, you must start
profiling, either manually or by including a console.profile() call in your script. To start profiling manually,
click the record button ( ) in the top right of the Profiles pane, and select Start JavaScript Profile in the
resulting menu. The record button turns red ( ). To stop the profile, click the record button again. No profile
is displayed until you stop profiling, either manually or through a call to console.profileEnd(). Each time
you begin and end profiling, another profile is captured.
Once you have captured one or more profiles, they are listed on the left side of Web Inspector. Manual profiles
are named sequentially (JavaScript Profile 1, JavaScript Profile 2, and so on). Profiles created by calls to
console.profile() are named with the title of the profile provided as an optional argument. If multiple
profiles are captured under the same name, a disclosure triangle reveals multiple runs within the profile.
The time spent in each function executed during the profile is displayed, as well as the number of times each
function is called, as shown in Figure 3-4. The time is displayed as a percentage of total time by default, but
you can view the time in seconds by clicking the percentage icon ( ).
Figure 3-4 Profiling JavaScript
The time spent is grouped into three categories: Self, the total time spent in the function itself; Total, the total
time spent in the function and any subordinate functions it calls in turn; and Average, the average time spent
in the function itself during each call (the Self time divided by the number of calls).
Timelines
Timing Profiles
34
If a function is declared with a name, the function name is displayed. If a function is created programmatically
by an eval() statement or inline <script> </script> tagset, it is labeled (program) in the profile. Other
unnamed functions, for example, a function defined within a variable declaration, are labeled (anonymous
function). To be less vague, you can rename anonymous functions in a profile by assigning a string value
to the displayName property of the function.
Where applicable, the source URL and line number of the function declaration is shown in gray to the right of
the function name. The source URL is a link. Clicking it opens the source in the content browser, scrolled to
the line number where the function is declared.
CSS Selector Profiling
Just as you can profile JavaScript, you can profile CSS selectors to measure their efficiency. The more general
a selector (such as a selector on a tag), the more time it takes to find all matches. More specific classes (such
as an ID or class) match fewer elements, and are faster for WebKit to find.
Figure 3-5 Profiling CSS
Timelines
Timing Profiles
35
If you are getting JavaScript errors on your webpage, you can use the Debugger navigation sidebar to assist
you in finding the cause of the problem. By setting breakpoints throughout your code, you can inspect the
values of your variables and observe the call stack during runtime.
Even if your JavaScript is minified, Web Inspector pretty-printsor expandsall of your scripts, allowing you
to set breakpoints on minified content.
Breakpoints
Breakpoints are markers you set on JavaScript resources to indicate a pause in script execution. You may already
be familiar with breakpoints if you have experience with compiled programming languages.
To add a breakpoint, select a JavaScript resource in the Resources navigation sidebar, and click a line number
in the gutter of the content browser. A blue marker is set, indicating that script execution will pause here the
next time this line runs. When a breakpoint is set, you can click it again to deactivate it, as shown in Figure 4-1.
Figure 4-1 An active breakpoint on line 17 and an inactive breakpoint on line 19
Important: Setting a breakpoint on a blank line does nothing. The line that you break on must contain
code, otherwise script execution wont pause at that line.
After one or more breakpoints are set, reload your page. Breakpoints retain their position across page loads,
so your breakpoints wont be lost. As soon as Safaris JavaScript interpreter reaches a line of code that has a
breakpoint on it, JavaScript execution halts, and the Scope Chain details sidebar appears. The Scope Chain
contains a snapshot of variables available to the scope of the paused line, as well as their current values. For
further information about the Scope Chain details sidebar, continue to Scope Chain (page 40).
36
Debugger
Every breakpoint you set across all your scripts appears under Breakpoints in the navigation sidebar, as shown
in Figure 4-2. Clicking the line jumps the text in the content browser to the line with the breakpoint. The
breakpoint icon to the right of the line number allows you to enable and disable the breakpoint without
removing it.
Figure 4-2 All breakpoints are listed in the navigation sidebar
By clicking the breakpoint icon in the Breakpoints pane, you disable all breakpoints. The breakpoint locations
are still saved, but JavaScript runs as if no breakpoints are set. Disabled breakpoints have a grayed-out
appearance, as shown in Figure 4-3.
Figure 4-3 An active and inactive breakpoint when breakpoints are disabled
You can also set a breakpoint within <script> tags on HTML resources.
Delete a breakpoint by selecting it in the Breakpoints pane and pressing the Delete key. You can also drag the
breakpoint out of the gutter to remove it.
You can set a breakpoint programmatically by calling the debugger keyword in your scripts. Dont ship this
code to your customers, though, because it will break the execution of your scripts at that point. It is meant
for development purposes only.
Debugger
Breakpoints
37
When a script is paused, you can hover over objects in your script to reveal a token popover containing the
objects methods and properties and their values at the current time, as shown in Figure 4-4.
Figure 4-4 Hovering over a variable inspects the object
Conditional Breakpoints
You can set breakpoints that are only active when a certain condition evaluates to be true. To do so, Right-click
the breakpoint in the Debugger details sidebar and select Edit Breakpoint, as shown in Figure 4-5.
Figure 4-5 Editing a breakpoint
Debugger
Breakpoints
38
A popover appears, prompting you to enter a condition, as shown in Figure 4-6.
Figure 4-6 Setting a conditional breakpoint
The condition is scoped to the current context; any variables within current scope are available to use in this
expression. If the condition evaluates to be true, the script pauses at the breakpoint; otherwise, the script
continues.
Call Stack
The call stack lists the functions that have been called and have not yet finished returning. The most recently
called functions are displayed at the top of the stack, as shown in Figure 4-7. Use this to view the order in
which functions are called.
Figure 4-7 The call stack
When a script is paused, the call stack shows the chain of functions called to arrive at the paused line. Selecting
an item in the stack jumps to where the line is declared in your scripts.
Debugger
Call Stack
39
Debugger Controls
Use the buttons above the call stack to have line-by-line control of where the debugger pauses execution next.
The buttons have the following behavior:
!
Continuecontinues execution until the next breakpoint.
!
Step oversteps to the next line, without descending into any functions called on the current line.
!
Step intosteps to the next line, descending into any functions called on the current line first. If
there are no function calls on the current line, this button behaves like the step over button.
!
Step outsteps to the preceding frame in the call stack.
Scope Chain
The Scope Chain details sidebar displays all the variables set on the page and their values at the moment in
time the script is paused. Variables are organized by their scope.
Debugger
Debugger Controls
40
Note: You can only access the Scope Chain details sidebar when a script is paused.
Local Variables
This includes all of the local variables available in the current functions scope. All variables defined within the
current function have their names printed here. Their values appear if they have been set at this point; otherwise,
the value is undefined.
Figure 4-8 Variables defined within the scope of the immediate function
There are two variables that appear in the local variables section that you dont declare explicitly: arguments
and this. The arguments variable contains the values of the arguments that were passed into this function,
including the implicitly available event object. this refers to the object this function is a member of (either
the object that this method is attached to, or window).
Debugger
Scope Chain
41
Important: Variables set without the var keyword fall out of local scope. If you dont declare a variable
with var, it appears under Global Variables instead of Local Variables. Doing so pollutes the global namespace,
so you should always declare local variables with var.
Closure Variables
If you set a breakpoint within a closure, or anonymous function, you see variables appear in the Closure Variables
section, as shown in Figure 4-9. Closures have privileged access to the scope of the outer function that calls
them.
Figure 4-9 Variables available to the current scope outside the immediate function
Global Variables
Variables attached to the global object window appear under the Global Variables section, as shown in Figure
4-10. This includes global variables you define in your scripts, global variables defined in installed extensions,
and methods and properties of window.
Figure 4-10 Variables in the global scope
Debugger
Scope Chain
42
The console offers a way to inspect and debug your webpages. Think of it as the Terminal of your web content.
The console has access to the DOM and JavaScript of the open page. Use the console as a tool to modify your
web content via interactive commands and as a teaching aid to expand your knowledge of JavaScript. Because
an objects methods and properties autocomplete as you type, you can see all available functions that are valid
in Safari.
For example, open the console and type $$(p)[1]. ($$ is shorthand for
document.querySelectorAllsee more shorthand commands in Table 5-1 (page 43).) Because this
paragraph is the second instance of the p element on this page ([1] in a 0-based index), the node represents
this paragraph. As you hover over the node, its position on the page is visibly highlighted. You can expand
the node to see its contents, and even press Command-C to copy it to your clipboard.
Command-Line API
You can inspect HTML nodes and JavaScript objects in more detail by using the console commands listed in
Table 5-1. Type the command-line APIs interactively within the console.
If your scripts share the same function name as a Command-Line API function, the function in your scripts
takes precedence.
Table 5-1 Commands available in the Web Inspector console
Description Command
Shorthand for document.querySelector. $(selector )
Shorthand for document.querySelectorAll. $$(selector )
Returns an array of elements that match the given XPath expression. $x(xpath)
Represents the currently selected node in the content browser. $0
Represents the last, second to last, third to last, and fourth to last
selected node in the content browser, respectively.
$1..4
Returns the value of the last evaluated expression. $_
43
The Console
Description Command
Prints all the properties of the object. dir(object )
Prints all the properties of the object. If the object is a node, prints
the node and all child nodes.
dirxml(object )
Prints an array of the names of the objects own properties. keys(object )
Prints an array of the values of the objects own properties. values(object )
Starts the JavaScript profiler. The optional argument title contains
the string to be printed in the header of the profile report. See
JavaScript Profiling (page 34).
profile([title] )
Stops the JavaScript profiler and prints its report. See JavaScript
Profiling (page 34).
profileEnd()
Prints an object containing the objects attached event listeners. getEventListeners(object )
Starts logging all events dispatched to the given object. The optional
argument types defines specific events or event types to log, such
as click.
monitorEvents(object[,
types] )
Stops logging for all events dispatched to the given object. The
optional argument types defines specific events or event types to
stop logging, such as click.
unmonitorEvents(object[,
types] )
Inspects the given object; this is the same as clicking the Inspect
button.
inspect(object )
Copies the given object to the clipboard. copy(object )
Clears the console. clear()
The functions listed in Table 5-1 are regular JavaScript functions that are part of the Web Inspector environment.
That means you can use them as you would any JavaScript function. For example, you can assign a chain of
Console API commands to a variable to create a useful shorthand. Listing 5-1 shows how you can quickly see
all event types attached to the selected node.
Listing 5-1 Find the events attached to this element
var evs = function () {
return keys(getEventListeners($0));
The Console
Command-Line API
44
};
After defining this function, inspect the magnifying glass in the top-right corner of this webpage, and type
evs() in the console. An array containing the string click is returned, because there is a click event listener
attached to that element.
Of course, these functions shouldnt be included in your websites JavaScript files because they are not available
in the browser environment. Only use these functions in the Web Inspector console. Console functions you
can include in your scripts are described in Console API (page 45).
Console API
You can output messages to the console, add markers to the timeline, and control the debugger directly from
your scripts by using the commands listed in Table 5-2.
Important: These functions exist to aid development and should not be included in any of your production
JavaScript.
Table 5-2 JavaScript functions available in the Console API
Description Function
Asserts whether the given expression is true. If the assertion fails,
prints the error and increments the number of errors in the
activity viewer. If the assertion succeeds, prints nothing.
console.assert(expression,
object)
Clears the console. console.clear()
Prints the number of times this line has been called. console.count([title])
Alias of console.log(). console.debug(object)
Prints the properties and values of the object. console.dir(object)
Prints the DOM tree of an HTML or XML node. console.dirxml(node)
Prints a message to the console with the error icon. Increments
the number of errors shown in the activity viewer.
console.error(object)
Prints subsequent logs under a disclosure of the given title. console.group([title])
Ends the previously declared console grouping. console.groupEnd()
The Console
Console API
45
Description Function
Alias of console.log(). console.info(object)
Prints the object to the console with the log icon. Increments
the number of logs shown in the activity viewer.
console.log(object)
Marks the Timeline with a green vertical dashed line that
indicates when this line of code was called. See Recording
Timelines (page 31).
console.markTimeline(label )
Starts the JavaScript profiler. The optional argument title
contains the string to be printed in the header of the profile
report. See JavaScript Profiling (page 34).
console.profile([title] )
Stops the JavaScript profiler and prints its report. See JavaScript
Profiling (page 34).
console.profileEnd([title] )
Starts a timer associated with the given name. Useful for timing
the duration of segments of code.
console.time(name )
Stops the timer associated with the given name and prints the
elapsed time to the console.
console.timeEnd(name )
Prints a stack trace at the moment the function is called. See
Figure 4-2 (page 37).
console.trace()
Prints a message to the console with the warning icon.
Increments the number of warnings shown in the activity viewer.
console.warn(object )
Stops JavaScript execution at the current line. This is the
equivalent of setting a breakpoint programmatically. See
Breakpoints (page 36).
debugger
The Console
Console API
46
The Develop menu contains a set of tools to assist you in prototyping, debugging, and optimizing your website:
!
Open Page WithOpen the current webpage in another web browser. Any app that registers as a viewer
for HTTP URLs appear here.
!
User AgentBrowsers send a user agent string that identifies the browser type and version to the server.
The same string is sent in response to a JavaScript request for the user agent string. Use this menu item
to modify the user agent string Safari sends, to simulate visiting your site using a different browser or
device type. See Changing the User Agent String (page 48).
!
Show Web InspectorOpen Web Inspector.
!
Show Error ConsoleOpen the console in Web Inspector. See The Console (page 43).
!
Show Page SourceOpen the Source Code in Web Inspector to see the HTML of the current page. See
Source versus DOM (page 17).
!
ShowPage ResourcesOpen the Resources navigation sidebar in Web Inspector to viewall images, scripts,
and style sheets attached to the current page. See Resources and the DOM (page 17).
!
ShowSnippet EditorOpen the Snippet Editor windowto interactively prototype HTML, CSS, or JavaScript
snippets. See Snippet Editor (page 50).
!
Show Extension BuilderOpen Extension Builder to install, modify, create, or uninstall a Safari extension.
See Safari Extensions Development Guide .
!
Start Profiling JavaScriptTurn on the JavaScript profiler to see how many times each function is called,
how long it takes, and so on. See JavaScript Profiling (page 34).
!
Start Timeline RecordingRecord detailed information about the status of incoming HTTP requests,
JavaScript events, and layout rendering. See Recording Timelines (page 31).
!
Empty CachesDelete all caches stored by the browser. Select this if youre suspicious that your webpage
is using stale cached content.
!
Disable CachesTurn off caching to see how a website loads the first time. Select this if youre suspicious
that your webpage is using stale cached content.
!
Disable ImagesTurn off image display and view websites as text only.
!
Disable StylesTurn off CSS style properties to view the page purely as HTML and JavaScript.
!
Disable JavaScriptView websites with the JavaScript interpreter disabled.
47
The Develop Menu
!
Disable Site-specific HacksUse this to disable the modifications to Safari and test your site for correct
operation (if Apple engineers have modified Safari specifically to work around a problemwith your website).
!
Disable Local File RestrictionsDisable security checks that may prohibit local development.
!
Enable WebGLTurn on the ability to view OpenGL content in Safari.
!
AllowJavaScript in the Address BarAllowJavaScript to be executed on the page by typing javascript:
followed by a valid JavaScript expression in the Address bar.
Changing the User Agent String
Every browser has a user agent string that identifies its type and version number. The browser sends this string
to the server. Your website can also use JavaScript to read the user agent string to determine which version
of a browser a user is running. You can choose what Safari reports as its user agent from the User Agent
submenu.
The Develop Menu
48
This can be useful to quickly test your code to see if it is reacting to various user agents as you expect, without
having to actually load the page in multiple versions of multiple browsers. The User Agent submenu is shown
in Figure A-1.
Figure A-1 The type and version of various browsers in the User Agent submenu
You can choose the common versions of most popular browsers from the submenu. Note that the list includes
the versions of Safari found on iPhone, iPad, and iPod touch.
The Other... menu item opens a sheet showing the default user agent string, which you can edit to any string
you like.
The Develop Menu
49
Snippet Editor
Snippet Editor provides an interactive sandbox for previewing HTML and CSS, as shown in Figure A-2.
Figure A-2 Snippet Editor can help you isolate problems with your markup
The Develop Menu
Snippet Editor
50
There are several keyboard commands that boost productivity when working in Web Inspector.
Navigation Shortcuts
Keyboard shortcut Action
Command-Option-I Toggle Web Inspector
Command-Option-C Toggle Console
Control-1 Resources navigation sidebar
Control-2 Timelines navigation sidebar
Control-3 Debugger navigation sidebar
Control-4 Console
Control-Shift-5 Scope Chain details sidebar
Control-Shift-4 Style details sidebar
Control-Shift-3 Layer details sidebar
Control-Shift-2 Node details sidebar
Control-Shift-1 Resource details sidebar
Command-Control-Left Arrow Show the previous view in the content browser
Command-Control-Right Arrow Show the next view in the content browser
51
Keyboard Shortcuts
DOM Tree Shortcuts
H Toggle selected elements visibility
Console Shortcuts
Esc Toggle Console
Tab Autocomplete
Up Arrow or Control-P Previous Command
Down Arrow or Control-N Next Command
Command-K or Control-L Clear
Command-Return Force Evaluation
Option-Return Force Newline
Debugger Shortcuts
Command-Option-Shift-P Start Profiling JavaScript
Command-Option-Shift-T Start Timeline Recording
Command-Control-Y or Command-/ Pause script execution
F6 or Command- Step over
F7 or Command-; Step into
F8 or Command-Shift-; Step out
Keyboard Shortcuts
DOM Tree Shortcuts
52
Miscellaneous Shortcuts
Command-R Reload page
Command-Shift-R Reload page without cache
Command-F Find
Command-Shift-F Search entire Inspector
Command-Z Undo
Command-Shift-Z Redo
Command-S Save file
Option-Shift-Up Arrow Increment number value by 10
Option-Up Arrow Increment number value by 1 (or by 0.1 if the value is between -1 and 1)
Option-Down Arrow Decrement number value by 1 (or by 0.1 if the value is between -1 and
1)
Option-Shift-Down Arrow Decrement number value by 10
Keyboard Shortcuts
Miscellaneous Shortcuts
53
This table describes the changes to Safari Web Inspector Guide .
Notes Date
Made a major organizational revision supporting OS X v10.9. Changed
name from"Safari Developer Tools Guide" to "Safari Web Inspector Guide".
2013-09-18
Updated screenshots to reflect new Web Inspector UI. 2012-07-23
Updated for Safari 5.1. Changed title from Safari User Guide for Web
Developers.
2011-07-21
Updated for Safari 5.0.1. Corrected typos and minor errors. 2010-08-26
Updated for Safari 5.0 2010-06-21
Added description of JavaScript 'console' API. 2010-01-20
Revised to be task-oriented, with sections on prototyping, debugging,
and optimizing websites.
2009-11-17
Revised and expanded for Safari 4.0. 2009-06-01
Added description of Safari Mobile debug console. 2009-01-06
Corrected typos.
Corrected minor typos and adjusted for style and consistency. 2008-10-15
Describes hidden developer tools introduced in Safari 3.1 2008-09-09
54
Document Revision History
Apple Inc.
Copyright 2013 Apple Inc.
All rights reserved.
No part of this publication may be reproduced,
stored in a retrieval system, or transmitted, in any
form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without
prior written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apples copyright notice.
No licenses, express or implied, are granted with
respect to any of the technology described in this
document. Apple retains all intellectual property
rights associated with the technology described
in this document. This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, iPad, iPhone, iPod, iPod
touch, Mac, OS X, Safari, and Xcode are
trademarks of Apple Inc., registered in the U.S.
and other countries.
App Store and Mac App Store are service marks
of Apple Inc.
Java is a registered trademark of Oracle and/or
its affiliates.
OpenGL is a registered trademark of Silicon
Graphics, Inc.
iOS is a trademark or registered trademark of
Cisco in the U.S. and other countries and is used
under license.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. ASARESULT, THISDOCUMENTISPROVIDED
AS IS, AND YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL
DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,
agent, or employee is authorized to make any
modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other
rights which vary from state to state.

Safari Developer Guide

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Safari Developer Guide

Enviado por

Direitos autorais:

Formatos disponíveis

Safari Web Inspector

Você também pode gostar