1 # Introduction to WebKit
5 [WebKit](https://webkit.org/) is an open-source Web browser engine.
6 It’s a framework in macOS and iOS, and used by many first party and third party applications including Safari, Mail, Notes, Books, News, and App Store.
8 The WebKit codebase is mostly written in C++ with bits of C and assembly, primarily in JavaScriptCore, and some Objective-C to integrate with Cocoa platforms.
10 It primarily consists of the following components, each inside its own directory in [Source](https://trac.webkit.org/browser/webkit/trunk/Source):
12 * **bmalloc** - WebKit’s malloc implementation as a bump pointer allocator. It provides an important security feature, called IsoHeap,
13 which segregates each type of object into its own page to prevent type confusion attacks upon use-after-free.
14 * **WTF** - Stands for Web Template Framework. WebKit’s template library.
15 The rest of the WebKit codebase is built using this template library in addition to, and often in place of, similar class templates in the C++ standard library.
16 It contains common container classes such as Vector, HashMap (unordered), HashSet, and smart pointer types such as Ref, RefPtr, and WeakPtr used throughout the rest of WebKit.
17 * **JavaScriptCore** - WebKit’s JavaScript engine; often abbreviated as JSC.
18 JSC parses JavaScript and generates byte code, which is then executed by one of the following four tiers.
19 Many tiers are needed to balance between compilation time and execution time.
20 Also see Phil's blog post about [Speculation in JavaScriptCore](https://webkit.org/blog/10308/speculation-in-javascriptcore/).
21 * **Interpreter** - This tier reads and executes instructions in byte code in C++.
22 * **Baseline JIT** - The first Just In Time compiler tier serves as the profiler as well as a significant speed up from the interpreter.
23 * **DFG JIT** - Data Flow Graph Just In Time compiler uses the data flow analysis to generate optimized machine code.
24 * **FTL JIT** - Faster than Light Just In Time compiler which uses [B3 backend](https://webkit.org/blog/5852/introducing-the-b3-jit-compiler/).
25 It’s the fastest tier of JSC.
26 JavaScriptCode also implements JavaScriptCore API for macOS and iOS applications.
27 * **WebCore** - The largest component of WebKit, this layer implements most of the Web APIs and their behaviors.
28 Most importantly, this component implements HTML, XML, and CSS parsers and implements HTML, SVG, and MathML elements as well as CSS.
29 It also implements [CSS JIT](https://webkit.org/blog/3271/webkit-css-selector-jit-compiler/), the only Just In Time compiler for CSS in existence.
30 It works with a few tree data structures:
31 * **Document Object Model** - This is the tree data structure we create from parsing HTML.
32 * **Render Tree** - This tree represents the visual representation of each element in DOM tree computed from CSS and also stores the geometric layout information of each element.
33 * **WebCore/PAL and WebCore/platform** - Whilst technically a part of WebCore, this is a platform abstraction layer for WebCore
34 so that the rest of WebCore code can remain platform independent / agnostic across all the platforms WebKit can run on: macOS, iOS, Windows, Linux, etc...
35 Historically, most of this code resided in WebCore/platform.
36 There is an ongoing multi-year project to slowly migrate code to PAL as we remove the reverse dependencies to WebCore.
37 * **WebKitLegacy** (a.k.a. WebKit1) - This layer interfaces WebCore with the rest of operating systems in single process and implements WebView on macOS and UIWebView on iOS.
38 * **WebKit** (a.k.a. WebKit2) - This layer implements the multi-process architecture of WebKit, and implements WKWebView on macOS and iOS.
39 WebKit’s multi-process architecture consists of the following processes:
40 * **UI process** - This is the application process. e.g. Safari and Mail
41 * **WebContent process** - This process loads & runs code loaded from websites.
42 Each tab in Safari typically has its own WebContent process.
43 This is important to keep each tab responsive and protect websites from one another.
44 * **Networking process** - This process is responsible for handling network requests as well as storage management.
45 All WebContent processes in a single session (default vs. private browsing) share a single networking session in the networking process.
46 * **WebInspector / WebDriver** - WebKit’s developer tool & automation tool for Web developers.
48 ## Contributing to WebKit
50 There are many ways to get involved and contribute to the WebKit Project.
51 Filing a new bug, fixing a bug, or adding a new feature.
53 There are three different kinds of contributors in the WebKit project.
55 * Contributor - This category encompasses everyone. Anyone who files a bug or contributes a code change or reviews a code change is considered as a contributor
56 * Committer - A committer is someone who has write access to [WebKit's subversion repository](https://svn.webkit.org/repository/webkit/).
57 * Reviewer - A reviewer is someone who has the right to review and approve code changes other contributors proposed.
59 See [Commit and Review Policy](https://webkit.org/commit-and-review-policy/) for more details on how to become a committer or a reviewer.
63 Before getting in touch with WebKit developers using any of the avenues below, make sure that you have checked our page on how to ask [questions about WebKit](https://webkit.org/asking-questions/).
65 You can find WebKit developers, testers, and other interested parties on the [#WebKit Slack workspace](https://webkit.slack.com/).
66 [Join the WebKit slack](https://join.slack.com/t/webkit/shared_invite/enQtOTU3NzQ3NTAzNjA0LTc5NmZlZWIwN2MxN2VjODVjNzEyZjBkOWQ4NTM3OTk0ZTc0ZGRjY2MyYmY2MWY1N2IzNTI2MTIwOGVjNzVhMWE),
69 ## Bug tracking in WebKit
71 [bugs.webkit.org](https://bugs.webkit.org/) hosted is the primary bug tracking tool we use.
72 When making a code change, we post a code change (patch) on this website.
74 ### Filing a bug and editing bugs
76 To [file a new WebKit bug](https://bugs.webkit.org/enter_bug.cgi), see [reporting bugs](https://webkit.org/reporting-bugs/).
78 To edit an existing bug, you may need [editbug-bits](https://webkit.org/bugzilla-bits/).
80 ### Code Reviews in bugs.webkit.org
82 We also use [bugs.webkit.org](https://bugs.webkit.org/) to upload & review code changes to WebKit.
83 You can post a code change with `Tools/Scripts/webkit-patch upload`.
84 Note that the `webkit-patch` script only looks for changes below current directory,
85 so generally you should change the current directory to the top-level directory of a WebKit first.
87 When a patch is posted on [bugs.webkit.org](https://bugs.webkit.org/) requesting a formal code review (r? flag is set),
88 The Early Warning System (a.k.a. EWS) will automatically build and run tests against your code change.
89 This allows contributors to find build or test failures before committing code changes to the WebKit’s primary Subversion repository.
91 Once a patch is approved by a reviewer (r+ flag is set),
92 then the patch can be either committed directly into the Subversion repository by a WebKit committer,
93 who has write access to the Subversion repository,
94 or via the commit queue which can be requested by setting cq? flag and approved by any WebKit committer by setting cq+.
96 The Subvesion commit message should be created by `Tools/Scripts/commit-log-editor` based on the change log entries.
97 `Tools/Scripts/webkit-patch land` does this automatically.
99 ### Security Bugs in bugs.webkit.org
101 Security bugs have their own components in [bugs.webkit.org](https://bugs.webkit.org/).
102 We’re also working on a new policy to delay publishing tests for security fixes until after the fixes have been widely deployed.
104 _***Do not post a patch or describe a security bug in a bug that is not in security component of bugs.webkit.org.***_
106 ## Getting started with WebKit
110 See [Getting the Code](https://github.com/WebKit/webkit/blob/master/ReadMe.md#getting-the-code)
112 ### Adding Tools to PATH
114 For convenience, you can add `Tools/Scripts/` to your path as follows in `~/.zshrc` like so:
117 export PATH=$PATH:/Volumes/Data/webkit/Tools/Scripts/
120 where `/Volumes/Data/webkit` is the path to a WebKit checkout.
122 This will allow you to run various tools you by name instead of typing the full path of the script.
124 ### Updating checkouts
126 There is a script to update a WebKit checkout: `Tools/Scripts/update-webkit`. This script will automatically merge change logs mentioned below.
130 [See Building WebKit](https://github.com/WebKit/webkit/blob/master/ReadMe.md#building-webkit)
132 ### Fixing mysterious build or runtime errors after Xcode upgrades
134 If you see mysterious build failures or if you’ve switched to a new version of
135 macOS or Xcode, delete the `WebKitBuild` directory.
136 `make clean` may not delete all the relevant files,
137 and building after doing that without deleting the `WebKitBuild` directory may result in mysterious build or dyld errors.
139 ### Building with Address Sanitizer to investigate memory corruption bugs
141 To build [Address Sanitizer](https://en.wikipedia.org/wiki/AddressSanitizer) or ASan builds to analyze security bugs,
142 run `Tools/Scripts/set-webkit-configuration --asan --release`.
143 This will enable ASan build. If want to attach a debugger, you can also specify `--debug` instead of `--release`.
144 Once you don’t need to build or run ASan anymore, you can specify `--no-asan` in place of `--asan` to disable ASan.
145 Note that this configuration is saved by creating a file called Asan in the WebKitBuild directory,
146 so if you are trying to do a clean Asan build by deleting the build directory you need to rerun this command.
150 You can also use Xcode to build & debug WebKit. Open `WebKit.xcworkspace` at the top level directory.
152 In order to make Xcode use build files built by `make` command above,
153 go to File > Workspace Settings... > Advanced... > Custom > Relative to Workspace
154 and adjust the relative paths of Products and Intermediates to point to `WebKitBuild` directory.
155 
156 
157 Note that debugging WebCore code typically requires attaching to the relevant WebContent process,
158 not the application process, which is mostly running code in [Source/WebKit/UIProcess](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/UIProcess).
159 Depending on what you’re debugging, you’d have to attach & debug different processes in the coalition.
161 You may find it useful to use the debug helpers under `Tools/lldb/lldb_webkit.py`.
162 This can be added to `~/.lldbinit` for automatic loading into LLDB on launch by adding the line `command script import {Path to WebKit}/Tools/lldb/lldb_webkit.py`.
163 For more details, see the Wiki article on [lldb formatters](https://trac.webkit.org/wiki/lldb%20formatters).
165 When debugging a debug build in LLDB, there are also a few functions that can be called on objects that will dump debugging info.
175 * showNodePathForThis()
177 ## Correctness Testing in WebKit
179 WebKit is really big on test driven development, we have many types of tests.
181 * **JavaScript tests** - Resides in top-level [JSTests](https://trac.webkit.org/browser/webkit/trunk/JSTests) directory.
182 This is the primary method of testing JavaScriptCore. Use `Tools/Scripts/run-javascriptcore-tests` to run these tests.
183 * **Layout tests** - Resides in top-level [LayoutTests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests) directory.
184 This is the primary method of testing WebCore.
185 If you’re making code changes to WebCore, you typically run these tests. Use `Tools/Scripts/run-webkit-tests` to run these.
186 Pass `-1` to run tests using WebKitLegacy (a.k.a. WebKit1).
187 [WebKitTestRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner) is used to run these tests for WebKit2,
188 and [DumpRenderTree](https://trac.webkit.org/browser/webkit/trunk/Tools/DumpRenderTree) is used to these tests for WebKit1.
189 There are a few styles of layout tests but all of them have a test file and expected result (ends with -expected.txt),
190 and the test passes if the test file’s output matches that of the expected result.
191 * **API tests** - Reside in [Tools/TestWebKitAPI](https://trac.webkit.org/browser/webkit/trunk/Tools/TestWebKitAPI),
192 these are [GTests](https://en.wikipedia.org/wiki/Google_Test) that test APIs exposed by JavaScriptCore,
193 WebKitLegacy, and WebKit layers as well as unit tests for selected WTF classes.
194 WebKit does not use [XCTests](https://developer.apple.com/documentation/xctest).
195 Use `Tools/Scripts/run-api-tests` to run these tests.
196 Because these API tests are sequentially, it’s preferable to write layout tests when possible.
197 * **Bindings tests** - Reside in [Source/WebCore/bindings/scripts/test](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/scripts/test),
198 these are tests for WebCore’s binding code generator.
199 Use `Tools/Scripts/run-bindings-tests` to run these tests.
200 * **webkitpy tests** - Tests for WebKit’s various Python scripts in [Tools/Scripts/webkitpy](https://trac.webkit.org/browser/webkit/trunk/Tools/Scripts/webkitpy).
201 Use `Tools/Scripts/test-webkitpy` to run these tests.
202 * **webkitperl tests** - Tests for WebKit’s various Perl scripts in [Tools/Scripts/webkitperl](https://trac.webkit.org/browser/webkit/trunk/Tools/Scripts/webkitperl).
203 Use `Tools/Scripts/test-webkitperl` to run these tests.
205 ## Performance Testing in WebKit
207 The WebKit project has a "no performance regression" policy.
208 We maintain the performance of the following of the benchmarks and are located under [PerformanceTests](https://trac.webkit.org/browser/webkit/trunk/PerformanceTests).
209 If your patch regresses one of these benchmarks even slightly (less than 1%), it will get reverted.
211 * **JetStream2** - Measures JavaScript and WASM performance.
212 * **MotionMark** - Measures graphics performance.
213 * **Speedometer 2** - Measures WebKit’s performance for complex web apps.
215 The following are benchmarks maintained by Apple's WebKit team but not available to other open source contributors
216 since Apple doesn't have the right to redistribute the content.
217 If your WebKit patch regresses one of these tests, your patch may still get reverted.
219 * **RAMification** - Apple's internal JavaScript memory benchmark.
220 * **ScrollPerf** - Apple's internal scrolling performance tests.
221 * **PLT** - Apple's internal page load time tests.
222 * **Membuster / PLUM** - Apple's internal memory tests. Membuster for macOS and PLUM for iOS and iPadOS.
224 ## Contributing code to WebKit
226 WebKit has a rigorous code contribution process and policy in place to maintain the quality of code.
230 Code you write must follow WebKit’s [coding style guideline](https://webkit.org/contributing-code/#code-style-guidelines).
231 You can run `Tools/Scripts/check-webkit-style` to check whether your code follows the coding guidelines or not
232 (it can report false positives or false negatives).
233 If you use `Tools/Scripts/webkit-patch upload` to upload your patch,
234 it automatically runs the style checker against the code you changed so there is no need to run `check-webkit-style` separately.
236 Some older parts of the codebase do not follow these guidelines.
237 If you are modifying such code, it is generally best to clean it up to comply with the current guidelines.
239 ### Convenience Tools
241 `Tools/Scripts/webkit-patch` provides a lot of utility functions like applying the latest patch on [bugs.webkit.org](https://bugs.webkit.org/) (`apply-from-bug`)
242 and uploading a patch (`upload --git-commit=<commit hash>`) to a [bugs.webkit.org](https://bugs.webkit.org/) bug.
243 Use `--all-commands` to the list of all commands this tool supports.
247 Much of the code we inherited from [KHTML](https://en.wikipedia.org/wiki/KHTML) is licensed under [LGPL](https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License).
248 New code contributed to WebKit will use the [two clause BSD license](https://trac.webkit.org/browser/trunk/Source/WebCore/LICENSE-APPLE).
249 When contributing new code, update the copyright date.
250 When moving the existing code, you need to include the original copyright notice for the moved code
251 and you should also not change the license, which may be BSD or LGPL depending on a file, without the permission of the copyright holders.
255 Once you have made a code change, you need to run the aforementioned tests (layout tests, API tests, etc...)
256 to make sure your code change doesn’t break existing functionality.
257 These days, uploading a patch on [bugs.webkit.org](https://bugs.webkit.org/) triggers the Early Warning System (a.k.a. EWS)
259 For any bug fix or a feature addition, there should be a new test demonstrating the behavior change caused by the code change.
260 If no such test can be written in a reasonable manner (e.g. the fix for a hard-to-reproduce race condition),
261 then the reason writing a tests is impractical should be explained in the accompanying change log.
263 Any patch which introduces new test failures or performance regressions may be reverted.
264 It’s in your interest to wait for the Early Warning System to fully build and test your patch on all relevant platforms.
268 ChangeLogs are simple text files which provide historical documentation for all changes to the WebKit project.
269 All patches require an entry to the ChangeLog.
271 The first line contains the date, your full name, and your email address.
272 Use this to write up a brief summary of the changes you’ve made.
273 Don’t worry about the “Reviewed by NOBODY (OOPS!)” line, the person landing your patch will fill this in.
274 There is one ChangeLog per top-level directory.
275 If you changed code and tests you will need to edit at least two ChangeLogs.
276 `Tools/Scripts/prepare-ChangeLog` script will create stub entries for ChangeLog files based on code changes you made in your Git or Subversion checkouts.
278 You should edit these stubs to describe your change, including the full URL to the bug (example entry, note that you can use `--bug` flag).
279 (You should set `EMAIL_ADDRESS` and `CHANGE_LOG_NAME` in your environment if you will be running this script frequently.)
280 A typical change log entry before being submitted to [bugs.webkit.org](https://bugs.webkit.org/) looks like this:
283 2012-10-04 Enrica Casucci <e•••••@apple.com>
285 Font::glyphDataAndPageForCharacter doesn't account for text orientation when using systemFallback on a cold cache.
286 https://bugs.webkit.org/show_bug.cgi?id=98452.
288 Reviewed by NOBODY (OOPS!).
290 The text orientation was considered only when there is a cache hit.
291 This change moves the logic to handle text orientation to a separate
292 inline function that is called also when the glyph is added to the cache.
294 Test: fast/text/vertical-rl-rtl-linebreak.html
296 * platform/graphics/FontFastPath.cpp:
297 (WebCore::applyTextOrientationForCharacter): Added.
298 (WebCore::Font::glyphDataAndPageForCharacter): Modified to use the new function in
299 both cases of cold and warm cache.
303 The “No new tests. (OOPS!)” line appears if `prepare-ChangeLog` did not detect the addition of new tests.
304 If your patch does not require test cases (or test cases are not possible), remove this line and explain why you didn’t write tests.
305 Otherwise all changes require test cases which should be mentioned in the ChangeLog.
307 ## WebKit’s Build System
309 Apple’s macOS, iOS, watchOS, and tvOS ports use Xcode and the rest use [CMake](https://en.wikipedia.org/wiki/CMake) to build WebKit.
310 There is an ongoing effort to make Apple's ports also use CMake.
312 In order to reduce the compilation time, which used to take 40+ minutes on the fully loaded 2018 15“ MacBook Pro,
313 we bundle up multiple C++ translation units (.cpp files) and compile them as a single translation unit.
314 We call this mechanism *Unified Sources* or *Unified Builds*.
316 Unified sources are generated under `WebKitBuild/X/DerivedSources` where X is the name of build configuration such as `Debug` and `Release-iphonesimulator`.
317 For example, `WebKitBuild/Debug/DerivedSources/WebCore/unified-sources/UnifiedSource116.cpp` may look like this:
320 #include "dom/Document.cpp"
321 #include "dom/DocumentEventQueue.cpp"
322 #include "dom/DocumentFragment.cpp"
323 #include "dom/DocumentMarkerController.cpp"
324 #include "dom/DocumentParser.cpp"
325 #include "dom/DocumentSharedObjectPool.cpp"
326 #include "dom/DocumentStorageAccess.cpp"
327 #include "dom/DocumentType.cpp"
330 ### How to add a new .h or .cpp file
332 To add a new header file or a translation unit (e.g. `.cpp`, `.m`, or `.mm`),
333 open WebKit.xcworkspace and add respective files in each directory.
335 Make sure to uncheck the target membership so that it’s not compiled as a part of the framework in xcodebuild.
336 Instead, add the same file in Sources.txt file that exists in each subdirectory of Source.
337 e.g. [Source/WebCore/Sources.txt](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/Sources.txt) for WebCore.
338 This will ensure the newly added file is compiled as a part of *unified sources*.
339 
340 When a header file in WTF is used in WebCore, or a header file in WebCore is used in WebKit or WebKitLegacy,
341 we need to export the file to those projects.
342 To do that, turn on the target membership in respective framework as set the membership to “Private” as seen below.
343 This will ensure the relevant header file is exported from WTF / WebCore to other downstream projects like WebKitLegacy.
344 
346 FIXME: Mention WTF_EXPORT_PRIVATE and WEBCORE_EXPORT.
348 FIXME: Add instructions on how to add files to CMake.
350 ### Build Failures with Unified Sources
352 Because of Unified Sources, it’s possible that adding a new file will cause a new build failure on some platform.
353 This happens because if `UnifiedSource1.cpp` contains `a.cpp`, `b.cpp`, `c.cpp`, then `#include` in `a.cpp` could have pulled in some header files that `c.cpp` needed.
354 When you add `b2.cpp`, and `c.cpp` moves to `UnifiedSource2.cpp`, `c.cpp` no longer benefits from `a.cpp` “accidentally” satisfying `c.cpp`’s header dependency.
355 When this happens, you need to add a new `#include` to `c.cpp` as it was supposed to be done in the first place.
357 ### Conditional Compilation
359 Every translation unit in WebKit starts by including “config.h”.
360 This file defines a set of [C++ preprocessor macros](https://en.cppreference.com/w/cpp/preprocessor)
361 used to enable or disable code based on the target operating system, platform, and whether a given feature is enabled or disabled.
363 For example, the following `#if` condition says that the code inside of it is only compiled if
364 [SERVICE_WORKER](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) feature is enabled:
367 #if ENABLE(SERVICE_WORKER)
372 Similarly, the following `#if` condition will enable the in-between code only on macOS:
380 For code which should be enabled in iOS, watchOS, tvOS, and Mac Catalyst we use `PLATFORM(IOS_FAMILY)`.
381 For each specific variant of iOS family, we also have `PLATFORM(IOS)`, `PLATFORM(WATCHOS)`, `PLATFORM(APPLETV)`, and `PLATFORM(MACCATALYST)`.
383 The following `#if` condition will enable the in-between code only if CoreGraphics is used:
391 Finally, if a certain piece of code should only be enabled in an operating system newer than some version,
392 we use `__IPHONE_OS_VERSION_MIN_REQUIRED` or `__MAC_OS_X_VERSION_MIN_REQUIRED`.
393 For example, the following #if enables the in-between code only on macOS 10.14 (macOS Mojave) or above:
396 #if PLATFORM(MAC) && __MAC_OS_X_VERSION_MIN_REQUIRED >= 101400
401 ## WebKit’s Continuous Integration Infrastructure
403 WebKit’s CI ([continuous integration](https://en.wikipedia.org/wiki/Continuous_integration)) infrastructure is located at [build.webkit.org](http://build.webkit.org/)).
405 [build.webkit.org](http://build.webkit.org/) will build and test commits from WebKit in the chronological order
406 and report test results to [results.webkit.org](http://results.webkit.org/).
407 Due to the chronological ordering, results could be a few hours behind during the work week.
410 We also have a dashboard to monitor the health of [build.webkit.org](http://build.webkit.org/)
411 at [build.webkit.org/dashboard](https://build.webkit.org/dashboard/).
412 If you observe that some bots are offline, or otherwise not processing your patch,
413 please notify [webkit-dev@webkit.org](mailto:webkit-dev@webkit.org).
415 This dashboard isn't great for investigating individual test failures,
416 [results.webkit.org](http://results.webkit.org/) is a better tool for such investigations.
417 It keeps track of individual test status by configuration over time.
418 You can search individual tests by name or look at the historical results of entire test suites.
419 These results will link back to the test runs in buildbot which are associated with a specific failure.
420 See layout tests section for more details on how to use these tools to investigate test failures observed on bots.
422 FIXME: Add a section about downloading build products from build.webkit.org.
424 # Memory Management in WebKit
426 In WebKit, when an object is owned by another object,
427 we typically use [`std::unique_ptr`](https://en.cppreference.com/w/cpp/memory/unique_ptr) to express that ownership.
428 WebKit uses two primary management strategies when objects in other cases:
429 [garbage collection](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) and [reference counting](https://en.wikipedia.org/wiki/Reference_counting).
431 ## Garbage collection in WebKit
435 ## Reference counting in WebKit
439 Most of WebCore objects are not managed by JavaScriptCore’s garbage collector.
440 Instead, we use [reference counting](https://en.wikipedia.org/wiki/Reference_counting).
441 We have two referencing counting pointer types:
442 [`RefPtr`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/RefPtr.h)
443 and [`Ref`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/Ref.h).
444 RefPtr is intended to behave like a C++ pointer whereas Ref is intended to behave like a C++ reference,
445 meaning that the former can be set to `nullptr` but the latter cannot.
448 Ref<A> a1; // This will result in compilation error.
449 RefPtr<A> a2; // This is okay.
450 Ref<A> a3 = A::create(); // This is okay.
451 a3->f(); // Calls f() on an instance of A.
457 Unlike C++‘s[`std::shared_ptr`](https://en.cppreference.com/w/cpp/memory/shared_ptr),
458 the implementation of referencing counting is a part of a managed object.
459 The requirements for an object to be used with `RefPtr` and `Ref` is as follows:
461 * It implements `ref()` and `deref()` member functions
462 * Each call to `ref()` and `deref()` will increment and decrement its internal reference counter
463 * The initial call to `ref()` is implicit in `new`,
464 after the object had been allocated and the constructor has been called upon;
465 i.e. meaning that the reference count starts at 1.
466 * When `deref()` is called when its internal reference counter reaches 0, “this” object is destructed and deleted.
468 There is a convenience super template class,
469 [`RefCounted<T>`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/RefCounted.h),
470 which implements this behavior for any inherited class T automatically.
472 ### How to use RefPtr and Ref
474 When an object which implements the semantics required by RefPtr and Ref is created via new,
475 we must immediately *adopt* it into `Ref` type using `adoptRef` as follows:
478 class A : public RefCounted<T> {
482 int f() { return m_foo; }
484 static Ref<A> create() { return adoptRef(*new A); }
490 This will create an instance of `Ref` without calling `ref()` on the newly created object, avoiding the unnecessary increment from 0 to 1.
491 WebKit’s coding convention is to make the constructor private and add a static `create` function
492 which returns an instance of a ref counted object after adopting it.
494 Note that returning RefPtr or Ref is efficient thanks to [copy elision](https://en.cppreference.com/w/cpp/language/copy_elision) in C++11,
495 and the following example does not create a temporary Ref object using copy constructor):
498 Ref<A> a = A::create();
501 When passing the ownership of a ref-counted object to a function,
502 use rvalue reference with `WTFMove` (equivalent to `std::move` with some safety checks),
503 and use a regular reference when there is a guarantee for the caller to keep the object alive as follows:
508 void setA(Ref<A>&& a) { m_a = WTFMove(a); }
520 Note that there is no `WTFMove` on `A::create` due to copy elision.
522 ### Forwarding ref and deref
524 As mentioned above, objects that are managed with `RefPtr` and `Ref` do not necessarily have to inherit from `RefCounted`.
525 One common alternative is to forward `ref` and `deref` calls to another object which has the ownership.
526 For example, in the following example, `Parent` class owns `Child` class.
527 When someone stores `Child` in `Ref` or `RefPtr`, the referencing counting of `Parent` is incremented and decremented on behalf of `Child`.
528 Both `Parent` and `Child` are destructed when the last `Ref` or `RefPtr` to either object goes away.
531 class Parent : RefCounted<Parent> {
533 static Ref<Parent> create() { return adoptRef(*new Parent); }
537 m_child = makeUnique<Child>(*this);
542 std::unique_ptr<Child> m_child;
547 ref() { m_parent.ref(); }
548 deref() { m_parent.deref(); }
551 Child(Parent& parent) : m_parent(parent) { }
560 A reference cycle occurs when an object X which holds `Ref` or `RefPtr` to another object Y which in turns owns X by `Ref` or `RefPtr`.
561 For example, the following code causes a trivial memory leak because A holds a `Ref` of B, and B in turn holds `Ref` of the A:
564 class A : RefCounted<A> {
566 static Ref<A> create() { return adoptRef(*new A); }
569 m_b = B::create(*this);
576 class B : RefCounted<B> {
578 static Ref<B> create(A& a) { return adoptRef(*new B(a)); }
586 We need to be particularly careful in WebCore with regards to garbage collected objects
587 because they often keep other ref counted C++ objects alive without having any `Ref` or `RefPtr` in C++ code.
588 It’s almost always incorrect to strongly keep JS value alive in WebCore code because of this.
590 ### ProtectedThis Pattern
592 Because many objects in WebCore are managed by tree data structures,
593 a function that operates on a node of such a tree data structure can end up deleting itself (`this` object).
594 This is highly undesirable as such code often ends up having a use-after-free bug.
596 To prevent these kinds of bugs, we often employ a strategy of adding `protectedThis` local variable of `Ref` or `RefPtr` type, and store `this` object as [follows](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/ContainerNode.cpp?rev=251041#L565):
599 ExceptionOr<void> ContainerNode::removeChild(Node& oldChild)
601 // Check that this node is not "floating".
602 // If it is, it can be deleted as a side effect of sending mutation events.
603 ASSERT(refCount() || parentOrShadowHostNode());
605 Ref<ContainerNode> protectedThis(*this);
607 // NotFoundError: Raised if oldChild is not a child of this node.
608 if (oldChild.parentNode() != this)
609 return Exception { NotFoundError };
611 if (!removeNodeWithScriptAssertion(oldChild, ChildChangeSource::API))
612 return Exception { NotFoundError };
614 rebuildSVGExtensionsElementsIfNecessary();
615 dispatchSubtreeModifiedEvent();
621 In this code, the act of removing `oldChild` can execute arbitrary JavaScript and delete `this` object.
622 As a result, `rebuildSVGExtensionsElementsIfNecessary` or `dispatchSubtreeModifiedEvent` might be called
623 after `this` object had already been free’ed if we didn’t have `protectedThis`,
624 which guarantees that this object’s reference count is at least 1
625 (because [Ref’s constructor](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/Ref.h?rev=250005#L63) increments the reference count by 1).
627 This pattern can be used for other objects that need to be *protected* from destruction inside a code block.
628 In the [following code](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/ContainerNode.cpp?rev=251041#L123),
629 `childToRemove` was passed in using C++ reference.
630 Because this function is going to remove this child node from `this` container node,
631 it can get destructed while the function is still running.
632 To prevent from having any chance of use-after-free bugs,
633 this function stores it in Ref (`protectedChildToRemove`) which guarantees the object to be alive until the function returns control back to the caller:
636 ALWAYS_INLINE bool ContainerNode::removeNodeWithScriptAssertion(Node& childToRemove, ChildChangeSource source)
638 Ref<Node> protectedChildToRemove(childToRemove);
639 ASSERT_WITH_SECURITY_IMPLICATION(childToRemove.parentNode() == this);
641 ScriptDisallowedScope::InMainThread scriptDisallowedScope;
642 ChildListMutationScope(*this).willRemoveChild(childToRemove);
647 Also see [Darin’s RefPtr Basics](https://webkit.org/blog/5381/refptr-basics/) for further reading.
649 ## Weak Pointers in WebKit
651 In some cases, it’s desirable to express a relationship between two objects without necessarily tying their lifetime.
652 In those cases, `WeakPtr` is useful. Like [std::weak_ptr](https://en.cppreference.com/w/cpp/memory/weak_ptr),
653 this class creates a non-owning reference to an object. There is a lot of legacy code which uses a raw pointer for this purpose,
654 but there is an ongoing effort to always use WeakPtr instead so do that in new code you’re writing.
656 To create a `WeakPtr` to an object, we need to make its class inherit from `CanMakeWeakPtr` as follows:
659 class A : CanMakeWeakPtr<A> { }
664 WeakPtr<A> weakA = makeWeakPtr(a);
668 Dereferencing a `WeakPtr` will return `nullptr` when the referenced object is deleted.
669 Because creating a `WeakPtr` allocates an extra `WeakPtrImpl` object,
670 you’re still responsible to dispose of `WeakPtr` at appropriate time.
674 While ordinary `HashSet` does not support having `WeakPtr` as its elements,
675 there is a specialized `WeakHashSet` class, which supports referencing a set of elements weakly.
676 Because `WeakHashSet` does not get notified when the referenced object is deleted,
677 the users / owners of `WeakHashSet` are still responsible for deleting the relevant entries from the set.
678 Otherwise, WeakHashSet will hold onto `WeakPtrImpl` until `computeSize` is called or rehashing happens.
680 # Understanding Document Object Model
684 [Document Object Model](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model)
685 (often abbreviated as DOM) is the tree data structured resulted from parsing HTML.
686 It consists of one or more instances of subclasses of [Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)
687 and represents the document tree structure. Parsing a simple HTML like this:
696 Will generate the following six distinct DOM nodes:
698 * [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document)
699 * [DocumentType](https://developer.mozilla.org/en-US/docs/Web/API/DocumentType)
700 * [HTMLHtmlElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html)
701 * [HTMLHeadElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)
702 * [HTMLBodyElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)
703 * [Text](https://developer.mozilla.org/en-US/docs/Web/API/Text) with the value of “hi”
705 Note that HTMLHeadElement (i.e. `<head>`) is created implicitly by WebKit
706 per the way [HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#parsing) is specified.
708 Broadly speaking, DOM node divides into the following categories:
710 * [Container nodes](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/ContainerNode.h) such as [Document](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Document.h), [Element](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Element.h), and [DocumentFragment](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/DocumentFragment.h).
711 * Leaf nodes such as [DocumentType](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/DocumentType.h), [Text](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Text.h), and [Attr](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Attr.h).
713 [Document](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Document.h) node,
714 as the name suggests a single HTML, SVG, MathML, or other XML document,
715 and is the [owner](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Node.h?rev=251008#L346) of every node in the document.
716 It is the very first node in any document that gets created and the very last node to be destroyed.
718 Note that a single web [page](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/Page.h) may consist of multiple documents
719 since [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
720 and [object](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object) elements may contain
721 a child [frame](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/Frame.h),
722 and form a [frame tree](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/FrameTree.h).
723 Because JavaScript can [open a new window](https://developer.mozilla.org/en-US/docs/Web/API/Window/open)
724 under user gestures and have [access back to its opener](https://developer.mozilla.org/en-US/docs/Web/API/Window/opener),
725 multiple web pages across multiple tabs might be able to communicate with one another via JavaScript API
726 such as [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
728 ## JavaScript Wrappers
730 Each DOM node’s behavior is implemented as a C++ class in WebCore.
731 JavaScript API is primarily implemented using [Web IDL](https://heycam.github.io/webidl/),
732 an [interface description language](https://en.wikipedia.org/wiki/Interface_description_language),
733 from which various [JS DOM binding code](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings)
734 is auto-generated by a [perl script](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/scripts/CodeGeneratorJS.pm),
735 for example, under `WebKitBuild/Debug/DerivedSources/WebCore/` for debug builds.
736 For example, C++ implementation of [Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)
737 is [Node class](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Node.h)
738 and its JavaScript interface is implemented by JSNode class,
739 most of which is auto-generated but has some custom bindings code in
740 [JSNodeCustom](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSNodeCustom.cpp).
741 Similarly, C++ implementation of [Range interface](https://developer.mozilla.org/en-US/docs/Web/API/Range)
742 is [Range class](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Range.h)
743 whilst its JavaScript API is implemented by the auto-generated JSRange class.
744 We call instances of the latter JS* classes *JS wrappers*.
746 These JS wrappers exist in what we call a [`DOMWrapperWorld`](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/DOMWrapperWorld.h).
747 Each `DOMWrapperWorld` has its own JS wrapper for each C++ object.
748 As a result, a single C++ object may have multiple JS wrappers in distinct `DOMWrapperWorld`s.
749 The most important `DOMWrapperWorld` is the main `DOMWrapperWorld` which runs the scripts of web pages WebKit loaded
750 while other `DOMWrapperWorld`s are typically used to run code for browser extensions and other code injected by applications that embed WebKit.
751 
752 JSX.h provides `toJS` functions which creates a JS wrapper for X
753 in a given [global object](https://developer.mozilla.org/en-US/docs/Glossary/Global_object)’s `DOMWrapperWorld`,
754 and toWrapped function which returns the underlying C++ object.
755 For example, `toJS` function for [Node](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Node.h)
756 is defined in [Source/WebCore/bindings/js/JSNodeCustom.h](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSNodeCustom.h).
758 When there is already a JS wrapper object for a given C++ object,
759 `toJS` function will find the appropriate JS wrapper in
760 a [hash map](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/DOMWrapperWorld.h?rev=251425#L53)
761 of the given `DOMWrapperWorld`.
762 Because a hash map lookup is expensive, some WebCore objects will inherit from
763 [ScriptWrappable](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/ScriptWrappable.h),
764 which has an inline pointer to the JS wrapper for the main world if one was already created.
766 ## JS Wrapper Lifecycle Management
768 As a general rule, a JS wrapper object keeps its underlying C++ object alive by means of reference counting
769 in [JSDOMWrapper](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSDOMWrapper.h) temple class
770 from which all JS wrappers in WebCore inherits.
771 However, **C++ objects do not keep their corresponding JS wrapper in each world alive** by the virtue of them staying alive
772 as such a circular dependency will result in a memory leak.
774 There are two primary mechanisms to keep JS wrappers alive in WebCore:
776 * **Visit Children** - When JavaScriptCore’s garbage collection visits some JS wrapper during
777 the [marking phase](https://en.wikipedia.org/wiki/Tracing_garbage_collection#Basic_algorithm),
778 visit another JS wrapper or JS object that needs to be kept alive.
779 * **Reachable from Opaque Roots** - Tell JavaScriptCore’s garbage collection that a JS wrapper is reachable
780 from an opaque root which was added to the set of opaque roots during marking phase.
782 FIXME: Explain how to add new IDL files and where derived sources are generated.
786 FIXME: Explain how visit children works.
790 FIXME: Explain how opaque roots work.
792 ## Inserting or Removing DOM Nodes
794 FIXME: Talk about how a node insertion or removal works.
796 # Understanding Style and Render Tree
798 FIXME: Describe rendering/layers/compositing
800 # Security Model of Web
802 For starters, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy.
804 FIXME: Write this section.
806 # WebKit2: WebKit’s Multi-Process Architecture
810 In order to safeguard the rest of the system and allow the application to remain responsive
811 even if the user had loaded web page that infinite loops or otherwise hangs,
812 the modern incarnation of WebKit uses multi-process architecture.
813 Web pages are loaded in its own *WebContent* process.
814 Multiple WebContent processes can share a browsing session, which lives in a shared network process.
815 In addition to handling all network accesses,
816 this process is also responsible for managing the disk cache and Web APIs that allow websites
817 to store structured data such as [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)
818 and [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API):
819 
820 Because a WebContent process can Just-in-Time compile arbitrary JavaScript code loaded from the internet,
821 meaning that it can write to memory that gets executed, this process is tightly sandboxed.
822 It does not have access to any file system unless the user grants an access,
823 and it does not have direct access to the underlying operating system’s [clipboard](https://en.wikipedia.org/wiki/Clipboard_(computing)),
824 microphone, or video camera even though there are Web APIs that grant access to those features.
825 Instead, UI process brokers such requests.
827 FIXME: How is IPC setup
829 FIXME: How to add / modify an IPC message
831 # Layout Tests: Tests of the Web for the Web
833 Layout tests are WebKit tests written using Web technology such as HTML, CSS, and JavaScript,
834 and it’s the primary mechanism by which much of WebCore is tested.
835 Relevant layout test should be ran while you’re making code changes to WebCore and before uploading a patch to [bugs.webkit.org](https://bugs.webkit.org/).
836 While [bugs.webkit.org](https://bugs.webkit.org/)’s Early Warning System will build and run tests on a set of configurations,
837 individual patch authors are ultimately responsible for any test failures that their patches cause.
839 ## Test Files and Expected Files
841 ### Directory Structure
843 [LayoutTests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests) directory is organized by the category of tests.
844 For example, [LayoutTests/accessibility](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/accessibility) contains accessibility related tests,
845 and [LayoutTests/fast/dom/HTMLAnchorElement](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/HTMLAnchorElement) contains
846 tests for [the HTML anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a).
848 Any file that ends in `.html`, `.htm`, `.shtml`, `.xhtml`, `.mht`, `.xht`, `.xml`, `.svg`, or `.php` is considered as a test
849 unless it’s preceded with `-ref`, `-notref`, `-expected`, or `-expected-mismatch` (these are used for ref tests; explained later).
850 It’s accompanied by another file of the same name except it ends in `-expected.txt` or `-expected.png`.
851 These are called *expected results* and constitutes the baseline output of a given test.
852 When layout tests are ran, the test runner generates an output in the form of a plain text file and/or an PNG image,
853 and it is compared against these expected results.
855 In the case expected results may differ from one platform to another,
856 the expected results for each test is stored in [LayoutTests/platform](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform).
857 The expected result of a given test exists in the corresponding directory in
858 each subdirectory of [LayoutTests/platform](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform).
859 For example, the expected result of [LayoutTests/svg/W3C-SVG-1.1/animate-elem-46-t.svg](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/svg/W3C-SVG-1.1/animate-elem-46-t.svg)
860 for macOS Mojave is located at [LayoutTests/platform/mac-mojave/svg/W3C-SVG-1.1/animate-elem-46-t-expected.txt](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform/mac-mojave/svg/W3C-SVG-1.1/animate-elem-46-t-expected.txt).
862 These platform directories have a fallback order.
863 For example, running tests for WebKit2 on macOS Catalina will use the following fallback path from the most specific to most generic:
865 * platform/mac-catalina-wk2 - Results for WebKit2 on macOS Catalina.
866 * platform/mac-catalina - Results for WebKit2 and WebKitLegacy on macOS Catalina.
867 * platform/mac-wk2 - Results for WebKit2 on all macOS.
868 * platform/mac - Results for all macOS.
869 * platform/wk2 - Results for WebKit2 on every operating system.
870 * generic - Next to the test file.
874 Tests under [LayoutTests/imported](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported) are imported from other repositories.
875 **They should not be modified by WebKit patches** unless the change is made in respective repositories first.
877 Most notable is [Web Platform Tests](https://web-platform-tests.org/),
878 which are imported under [LayoutTests/imported/w3c/web-platform-tests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported/w3c/web-platform-tests).
879 These are cross browser vendor tests developed by W3C. Mozilla, Google, and Apple all contribute many tests to this shared test repository.
883 FIXME: Explain how to start and open tests that require HTTP server.
887 FIXME: Explain how test expectations work.
889 ## Running Layout Tests
891 To run layout tests, use `Tools/Scripts/run-webkit-tests`.
892 It optionally takes file paths to a test file or directory and options on how to run a test.
893 For example, in order to just run `LayoutTests/fast/dom/Element/element-traversal.html`, do:
896 Tools/Scripts/run-webkit-tests fast/dom/Element/element-traversal.html
899 Because there are 50,000+ tests in WebKit,
900 you typically want to run a subset of tests that are relevant to your code change
901 (e.g. `LayoutTests/storage/indexeddb/` if you’re working on IndexedDB) while developing the code change,
902 and run all layout tests at the end on your local machine or rely on the Early Warning System on [bugs.webkit.org](https://bugs.webkit.org/) for more thorough testing.
904 Specify `--debug` or `--release` to use either release or debug build.
905 To run tests using iOS simulator, you can specify either `--ios-simulator`, `--iphone-simulator`,
906 or `--ipad-simulator` based on whichever simulator is desired.
908 By default, `run-webkit-tests` will run all the tests you specified once in the lexicological order of test paths
909 relative to `LayoutTests` directory and retry any tests that have failed.
910 If you know the test is going to fail and don’t want retries, specify `--no-retry-failures`.
912 Because there are so many tests, `run-webkit-tests` will runs tests in different directories in parallel
913 (i.e. all tests in a single directory is ran sequentially one after another).
914 You can control the number of parallel test runners using `--child-processes` option.
916 `run-webkit-tests` has many options.
917 Use `--help` to enumerate all the supported options.
919 ### Repeating Layout Tests
921 When you’re investigating flaky tests or crashes, it might be desirable to adjust this.
922 `--iterations X` option will specify the number of times the list of tests are ran.
923 For example, if we are running tests A, B, C and `--iterations 3` is specified,
924 `run-webkit-tests` will run: A, B, C, A, B, C, A, B, C.
925 Similarly, `--repeat-each` option will specify the number of times each test is repeated before moving onto next test.
926 For example, if we’re running tests A, B, C, and `--repeat-each 3` is specified, `run-webkit-tests` will run: A, A, A, B, B, B, C, C, C.
927 `--exit-after-n-failures` option will specify the total number of test failures before `run-webkit-tests` will stop.
928 In particular, `--exit-after-n-failures=1` is useful when investigating a flaky failure
929 so that `run-webkit-tests` will stop when the failure actually happens for the first time.
933 Whenever tests do fail, run-webkit-tests will store results in `WebKitBuild/Debug/layout-test-results`
934 mirroring the same directory structure as `LayoutTests`.
935 For example, the actual output produced for `LayoutTests/editing/inserting/typing-001.html`,
936 if failed, will appear in `WebKitBuild/Debug/layout-test-results/editing/inserting/typing-001-actual.txt`.
937 run-webkit-tests also generates a web page with the summary of results in
938 `WebKitBuild/Debug/layout-test-results/results.html` and automatically tries to open it in Safari using the local build of WebKit.
940 > If Safari fails to launch, specify `--no-show-results` and open results.html file manually.
942 ### Updating Expected Results
944 If you’ve updated a test content or test’s output changes with your code change (e.g. more test case passes),
945 then you may have to update `-expected.txt` file accompanying the test.
946 To do that, first run the test once to make sure the diff and new output makes sense in results.html,
947 and run the test again with `--reset-results`.
948 This will update the matching `-expected.txt` file.
950 You may need to manually copy the new result to other -expected.txt files that exist under `LayoutTests` for other platforms and configurations.
951 Find other `-expected.txt` files when you’re doing this.
953 When a new test is added, `run-webkit-tests` will automatically generate new `-expected.txt` file for your test.
954 You can disable this feature by specifying `--no-new-test-results` e.g. when the test is still under development.
956 ## Different Styles of Layout Tests
958 There are multiple styles of layout tests in WebKit.
960 ### **Render tree dumps**
962 This is the oldest style of layout tests, and the default mode of layout tests.
963 It’s a text serialization of WebKit’s render tree and its output looks like
964 [this](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform/mac/fast/dom/anchor-text-expected.txt):
967 layer at (0,0) size 800x600
968 RenderView at (0,0) size 800x600
969 layer at (0,0) size 800x600
970 RenderBlock {HTML} at (0,0) size 800x600
971 RenderBody {BODY} at (8,8) size 784x584
972 RenderInline {A} at (0,0) size 238x18 [color=#0000EE]
973 RenderInline {B} at (0,0) size 238x18
974 RenderText {#text} at (0,0) size 238x18
975 text run at (0,0) width 238: "the second copy should not be bold"
976 RenderText {#text} at (237,0) size 5x18
977 text run at (237,0) width 5: " "
978 RenderText {#text} at (241,0) size 227x18
979 text run at (241,0) width 227: "the second copy should not be bold"
982 This style of layout tests is discouraged today because its outputs are highly dependent on each platform,
983 and end up requiring a specific expected result in each platform.
984 But they’re still useful when testing new rendering and layout feature or bugs thereof.
986 These tests also have accompanying `-expected.png` files but `run-webkit-tests` doesn't check the PNG output against the expected result by default.
987 To do this check, pass `--pixel`.
988 Unfortunately, many *pixel tests* will fail because we have not been updating the expected PNG results a good chunk of the last decade.
989 However, these pixel results might be useful when diagnosing a new test failure.
990 For this reason, `run-webkit-tests` will automatically generate PNG results when retrying the test,
991 effectively enabling `--pixel` option for retries.
995 These are tests that uses the plain text serialization of the test page as the output (as if the entire page’s content is copied as plain text).
996 All these tests call `testRunner.dumpAsText` to trigger this behavior.
997 The output typically contains a log of text or other informative output scripts in the page produced.
998 For example, [LayoutTests/fast/dom/anchor-toString.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/anchor-toString.html) is written as follows:
1001 <a href="http://localhost/sometestfile.html" id="anchor">
1008 if (window.testRunner)
1009 testRunner.dumpAsText();
1011 var anchor = document.getElementById("anchor");
1012 document.write("Writing just the anchor object - " + anchor);
1014 var anchorString = String(anchor);
1015 document.write("<br><br>Writing the result of the String(anchor) - " + anchorString);
1017 var anchorToString = anchor.toString();
1018 document.write("<br><br>Writing the result of the anchor's toString() method - " + anchorToString);
1023 and generates the following [output](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/anchor-toString-expected.txt):
1028 Writing just the anchor object - http://localhost/sometestfile.html
1030 Writing the result of the String(anchor) - http://localhost/sometestfile.html
1032 Writing the result of the anchor's toString() method - http://localhost/sometestfile.html
1035 ### js-test.js and js-test-pre.js tests
1037 These are variants of dumpAsText test which uses WebKit’s assertion library:
1038 [LayoutTests/resources/js-test.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test.js)
1039 and [LayoutTests/resources/js-test-pre.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test-pre.js).
1040 It consists of shouldX function calls which takes two JavaScript code snippet which are then executed and outputs of which are compared.
1041 js-test.js is simply a new variant of js-test-pre.js that doesn’t require
1042 the inclusion of [LayoutTests/resources/js-test-post.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test-post.js) at the end.
1043 **Use js-test.js in new tests**, not js-test-pre.js.
1045 For example, [LayoutTests/fast/dom/Comment/remove.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/Comment/remove.html)
1046 which tests [remove()](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove) method
1047 on [Comment node](https://developer.mozilla.org/en-US/docs/Web/API/Comment) is written as:
1051 <script src="../../../resources/js-test-pre.js"></script>
1052 <div id="test"></div>
1055 description('This tests the DOM 4 remove method on a Comment.');
1057 var testDiv = document.getElementById('test');
1058 var comment = document.createComment('Comment');
1059 testDiv.appendChild(comment);
1060 shouldBe('testDiv.childNodes.length', '1');
1062 shouldBe('testDiv.childNodes.length', '0');
1064 shouldBe('testDiv.childNodes.length', '0');
1067 <script src="../../../resources/js-test-post.js"></script>
1070 with the following [expected result](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/Comment/remove-expected.txt) (output):
1073 This tests the DOM 4 remove method on a Comment.
1075 On success, you will see a series of "PASS" messages, followed by "TEST COMPLETE".
1078 PASS testDiv.childNodes.length is 1
1079 PASS testDiv.childNodes.length is 0
1080 PASS testDiv.childNodes.length is 0
1081 PASS successfullyParsed is true
1086 `description` function specifies the description of this test, and subsequent shouldBe calls takes two strings,
1087 both of which are evaluated as JavaScript and then compared.
1089 Some old js-test-pre.js tests may put its test code in a separate JS file but we don’t do that anymore to keep all the test code in one place.
1091 [js-test.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test.js) and [js-test-pre.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test-pre.js) provide all kinds of other assertion and helper functions.
1092 Here are some examples:
1094 * `debug(msg)` - Inserts a debug / log string in the output.
1095 * `evalAndLog(code)` - Similar to `debug()` but evaluates code as JavaScript.
1096 * `shouldNotBe(a, b)` - Generates `PASS` if the results of evaluating `a` and `b` differ.
1097 * `shouldBeTrue(code)` - Shorthand for `shouldBe(code, 'true')`.
1098 * `shouldBeFalse(code)` - Shorthand for `shouldBe(code, 'false')`.
1099 * `shouldBeNaN(code)` - Shorthand for `shouldBe(code, 'NaN')`.
1100 * `shouldBeNull(code)` - Shorthand for `shouldBe(code, 'null')`.
1101 * `shouldBeZero(code)` - Shorthand for `shouldBe(code, '0')`.
1102 * `shouldBeEqualToString(code, string)` - Similar to `shouldBe` but the second argument is not evaluated as string.
1103 * `finishJSTest()` - When js-test.js style test needs to do some async work, define the global variable named jsTestIsAsync and set it to true. When the test is done, call this function to notify the test runner (don’t call `testRunner.notifyDone` mentioned later directly). See [an example](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/iframe-innerWidth.html).
1105 **It’s important to note that these shouldX functions only add output strings that say PASS or FAIL. If the expected result also contains the same FAIL strings, then run-webkit-tests will consider the whole test file to have passed.**
1107 Another way to think about this is that `-expected.txt` files are baseline outputs, and baseline outputs can contain known failures.
1109 There is a helper script to create a template for a new js-test.js test. The following will create new test named `new-test.html` in [LayoutTests/fast/dom](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom):
1112 Tools/Scripts/make-new-script-test fast/dom/new-test.html
1115 ### dump-as-markup.js Tests
1117 A dump-as-markup.js test is yet another variant of dumpAsText test,
1118 which uses [LayoutTests/resources/dump-as-markup.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/dump-as-markup.js).
1119 This style of test is used when it’s desirable to compare the state of the DOM tree before and after some operations.
1120 For example, many tests under [LayoutTests/editing](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/editing)
1121 use this style of testing to test complex DOM mutation operations such as pasting HTML from the users’ clipboard.
1122 dump-as-markup.js adds `Markup` on the global object and exposes a few helper functions.
1123 Like js-test.js tests, a test description can be specified via `Markup.description`.
1124 The test then involves `Markup.dump(node, description)` to serialize the state of DOM tree as plain text
1125 where `element` is either a DOM [node](https://developer.mozilla.org/en-US/docs/Web/API/Node)
1126 under which the state should be serialized or its [id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
1128 For example, [LayoutTests/editing/inserting/insert-list-in-table-cell-01.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/editing/inserting/insert-list-in-table-cell-01.html) is written as follows:
1132 <div id="container" contenteditable="true"><table border="1"><tr><td id="element">fsdf</td><td>fsdf</td></tr><tr><td>gghfg</td><td>fsfg</td></tr></table></div>
1133 <script src="../editing.js"></script>
1134 <script src="../../resources/dump-as-markup.js"></script>
1136 Markup.description('Insert list items in a single table cell:');
1138 var e = document.getElementById("element");
1139 setSelectionCommand(e, 0, e, 1);
1140 Markup.dump('container', 'Before');
1142 document.execCommand("insertOrderedList");
1143 Markup.dump('container', 'After');
1147 with the following [expected result](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/editing/inserting/insert-list-in-table-cell-01-expected.txt):
1150 Insert list items in a single table cell:
1159 | "<#selection-anchor>fsdf<#selection-focus>"
1177 | "<#selection-anchor>fsdf<#selection-focus>"
1188 ### testharness.js Tests
1190 This is yet another variant of dumpAsText test which uses the test harness of [Web Platform Tests](https://web-platform-tests.org/),
1191 which is [W3C](https://www.w3.org/)’s official tests for the Web.
1192 There is an [extensive documentation](https://web-platform-tests.org/writing-tests/testharness-api.html) on how this harness works.
1194 > As mentioned above, do not modify tests in [LayoutTests/imported/w3c/web-platform-tests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported/w3c/web-platform-tests)
1195 unless the same test changes are made in Web Platform Tests’ primary repository.
1199 Reference tests are special in that they don’t have accompanying `-expected.txt` files.
1200 Instead, they have a matching or mismatching expected result file.
1201 Both the test file and the accompanying matching or mismatching expected result generate PNG outputs.
1202 The test passes if the PNG outputs of the test and the matching expected result are the same; the test fails otherwise.
1203 For a test with a mismatching expected result, the test passes if the PNG outputs of the test and the mismatching expected result are not the same, and fails if they are the same.
1205 A matching expected result or a mismatching expected result can be specified in a few ways:
1207 * The file with the same name as the test name except it ends with `-expected.*` or `-ref.*` is a matching expected result for the test.
1208 * The file with the same name as the test name except it ends with `-expected-mismatch.*` or `-notref.*` is a matching expected result for the test.
1209 * The file specified by a HTML link element in the test file with `match` relation: `<link rel=match href=X>` where X is the relative file path is a matching expected result.
1210 * The file specified by a HTML link element in the test file with `mismatch` relation: `<link rel=mismatch href=X>` where X is the relative file path is a mismatching expected result.
1212 For example, [LayoutTests/imported/w3c/web-platform-tests/2dcontext/line-styles/lineto_a.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported/w3c/web-platform-tests/2dcontext/line-styles/lineto_a.html) specifies [lineto_ref.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported/w3c/web-platform-tests/2dcontext/line-styles/lineto_ref.html) in the same directory as the matching expected result as follows:
1216 <meta charset=utf-8>
1217 <link rel=match href=lineto_ref.html>
1224 <canvas id="c" width="150" height="150" >
1225 Your browser does not support the HTML5 canvas tag.</canvas>
1228 var c = document.getElementById("c");
1229 var ctx = c.getContext("2d");
1233 ctx.lineTo(20, 130);
1234 ctx.lineTo(130, 130);
1235 ctx.lineTo(130, 20);
1238 ctx.fillStyle = '#90EE90';
1245 Most layout tests are designed to be runnable inside a browser but run-webkit-tests uses a special program to run them.
1246 Our continuous integration system as well as the Early Warning System uses run-webkit-tests to run layout tests.
1247 In WebKit2, this is appropriately named [WebKitTestRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner).
1248 In WebKit1 or WebKitLegacy, it’s [DumpRenderTree](https://trac.webkit.org/browser/webkit/trunk/Tools/DumpRenderTree),
1249 which is named after the very first type of layout tests, which generated the text representation of the render tree.
1251 ### Extra Interfaces Available in Test Runners
1253 Both WebKitTestRunner and DumpRenderTree expose a few extra interfaces to JavaScript on `window` (i.e. global object) in order to emulate user inputs,
1254 enable or disable a feature, or to improve the reliability of testing.
1256 * **[GCController](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/GCController.idl)**
1257 - `GCController.collect()` triggers a synchronous full garbage collection.
1258 This function is useful for testing crashes or erroneous premature collection of JS wrappers and leaks.
1259 * **[testRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/TestRunner.idl)**
1260 - TestRunner interface exposes many methods to control the behaviors of WebKitTestRunner and DumpRenderTree.
1261 Some the most commonly used methods are as follows:
1262 * `waitUntilDone()` / `notifyDone()` - These functions are useful when writing tests that involve asynchronous tasks
1263 which may require the test to continue running beyond when it finished loading.
1264 `testRunner.waitUntilDone()` makes WebKitTestRunner and DumpRenderTree not end the test when a layout test has finished loading.
1265 The test continues until `testRunner.notifyDone()` is called.
1266 * `dumpAsText(boolean dumpPixels)` - Makes WebKitTestRunner and DumpRenderTree output the plain text of the loaded page instead of the state of the render tree.
1267 * `overridePreference(DOMString preference, DOMString value)` - Overrides WebKit’s preferences.
1268 For WebKit2, these preferences are defined in [Source/WebKit/Shared/WebPreferences.yaml](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/Shared/WebPreferences.yaml).
1269 For WebKitLegacy, these are defined in [Source/WebKitLegacy/mac/WebView/WebPreferences.h](https://trac.webkit.org/browser/webkit/trunk/Source/WebKitLegacy/mac/WebView/WebPreferences.h) for macOS
1270 and [Source/WebKitLegacy/win/WebPreferences.h](https://trac.webkit.org/browser/webkit/trunk/Source/WebKitLegacy/win/WebPreferences.h) for Windows.
1271 * **[eventSender](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/EventSendingController.idl)**
1272 - Exposes methods to emulate mouse, keyboard, and touch actions.
1273 **Use [ui-helpers.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/ui-helper.js) script** instead of directly calling methods on this function.
1274 This will ensure the test will be most compatible with all the test configurations we have.
1275 * [**UIScriptController**](https://trac.webkit.org/browser/webkit/trunk/Tools/TestRunnerShared/UIScriptContext/Bindings/UIScriptController.idl)
1276 - Exposes methods to emulate user inputs like eventSender mostly on iOS WebKit2.
1277 **Use [ui-helpers.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/ui-helper.js) script** instead of directly calling methods on this function.
1278 This will ensure the test will be most compatible with all the test configurations we have.
1279 * **[textInputController](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/TextInputController.idl)**
1280 - Exposes methods to test [input methods](https://en.wikipedia.org/wiki/Input_method).
1282 Additionally, [WebCore/testing](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing) exposes a few testing hooks to test its internals:
1284 * **[internals](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing/Internals.idl)**
1285 - Exposes various hooks into WebCore that shouldn’t be part of WebKit or WebKitLegacy API.
1286 * [**internals.settings**](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing/InternalSettings.idl)
1287 - Exposes various WebCore settings and let tests override them.
1288 Note that WebKit layer code depends on [Source/WebKit/Shared/WebPreferences.yaml](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/Shared/WebPreferences.yaml),
1289 and will not respect this override.
1290 Because of this, it’s preferable to override the equivalent preference via `testRunner.overridePreference`
1291 unless you know for sure WebKit or WebKitLegacy layer of code isn’t affected by the setting you’re overriding.
1293 ### Enabling or Disabling a Feature in Test Runners
1295 FIXME: Mention test-runner-options
1297 ## Test Harness Scripts
1299 FIXME: Write about dump-as-markup.js, and ui-helper.js
1301 ## Investigating Test Failures Observed on Bots
1303 There are multiple tools to investigate test failures happening on our continuous integration system
1304 ([build.webkit.org](http://build.webkit.org/)).
1305 The most notable is flakiness dashboard:
1306 [results.webkit.org](https://results.webkit.org/)
1308 FIXME: Write how to investigate a test failure.
1310 ## Debugging Layout Tests in Xcode
1312 The easiest way to debug a layout test is with WebKitTestRunner or DumpRenderTree.
1313 In Product > Scheme, select “All Source”.
1315 In Product > Scheme > Edit Scheme, open “Run” tab.
1316 Pick WebKitTestRunner or DumpRenderTree, whichever is desired in “Executable”.
1318 
1319 Go to Arguments and specify the path to the layout tests being debugged relative to where the build directory is located.
1320 e.g. `../../LayoutTests/fast/dom/Element/element-traversal.html` if `WebKitBuild/Debug` is the build directory.
1321 
1322 You may want to specify OS_ACTIVITY_MODE environmental variable to “disable”
1323 in order to suppress all the system logging that happens during the debugging session.
1325 You may also want to specify `--no-timeout` option to prevent WebKitTestRunner or DumpRenderTree
1326 to stop the test after 30 seconds if you’re stepping through code.
1328 Once this is done, you can run WebKitTestRunner or DumpRenderTree by going to Product > Perform Action > Run without Building.
1330 Clicking on “Run” button may be significantly slower due to Xcode re-building every project and framework each time.
1331 You can disable this behavior by going to “Build” tab and unchecking boxes for all the frameworks involved for “Run”:
1332 
1334 ### Attaching to WebContent Process
1336 You may find Xcode fails to attach to WebContent or Networking process in the case of WebKitTestRunner.
1337 In those cases, attach a breakpoint in UIProcess code
1338 such as [`TestController::runTest` in WebKitTestRunner right before `TestInvocation::invoke` is called](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/TestController.cpp?rev=252228#L1701).
1339 Once breakpoint is hit in the UIProcess, attach to `WebContent.Development` or `Networking.Development` process manually in Xcode via Debug > Attach to Process.
1341 # Dive into API tests
1343 FIXME: Talk about how to debug API tests.
1349 Each framework (WebCore, WebKit, WebKitLegacy, WTF) enable their own logging infrastructure independently (though the infrastructure itself is shared). If you want to log a message, `#include` the relevant framework's `Logging.h` header. Then, you can use the macros below.
1351 Beware that you can't `#include` multiple framework's `Logging.h` headers at the same time - they each define a macro `LOG_CHANNEL_PREFIX` which will conflict with each other. Only `#include` the `Logging.h` header from your specific framework.
1353 If you want to do more advanced operations, like searching through the list of log channels, `#include` your framework's `LogInitialization.h` header. These do not conflict across frameworks, so you can do something like
1356 #include "LogInitialization.h"
1357 #include <WebCore/LogInitialization.h>
1358 #include <WTF/LogInitialization.h>
1361 Indeed, WebKit does this to initialize all frameworks' log channels during Web Process startup.
1365 There are a few relevant macros for logging messages:
1367 - `LOG()`: Log a printf-style message in debug builds. Requires you to name a logging channel to output to.
1368 - `LOG_WITH_STREAM()` Log an iostream-style message in debug builds. Requires you to name a logging channel to output to.
1369 - `RELEASE_LOG()`: Just like `LOG()` but logs in both debug and release builds. Requires you to name a logging channel to output to.
1370 - `WTFLogAlways()`: Mainly for local debugging, unconditionally output a message. Does not require a logging channel to output to.
1372 Here's an example invocation of `LOG()`:
1375 LOG(MediaQueries, "HTMLMediaElement %p selectNextSourceChild evaluating media queries", this);
1378 That first argument is a log channel. These have 2 purposes:
1380 - Individual channels can be enabled/disabled independently (So you can get all the WebGL logging without getting any Loading logging)
1381 - When multiple channels are enabled, and you're viewing the logs, you can search/filter by the channel
1383 Here's an example invocation of `LOG_WITH_STREAM()`:
1386 LOG_WITH_STREAM(Scrolling, stream << "ScrollingTree::commitTreeState - removing unvisited node " << nodeID);
1389 The macro sets up a local variable named `stream` which the second argument can direct messages to. The second argument is a collection of statements - not expressions like `LOG()` and `RELEASE_LOG()`. So, you can do things like this:
1392 LOG_WITH_STREAM(TheLogChannel,
1393 for (const auto& something : stuffToLog)
1394 stream << " " << something;
1398 The reason why (most of) these use macros is so the entire thing can be compiled out when logging is disabled. Consider this:
1401 LOG(TheLogChannel, "The result is %d", someSuperComplicatedCalculation());
1404 If these were not macros, you'd have to pay for `someSuperComplicatedCalculation()` whether logging is enabled or not.
1406 ## Enabling and disabling log channels
1408 Channels are enabled/disabled at startup by passing a carefully crafted string to `initializeLogChannelsIfNecessary()`. On the macOS and iOS ports, this string comes from the _defaults_ database. On other UNIX systems and Windows, it comes from environment variables.
1410 You can read the grammar of this string in `initializeLogChannelsIfNecessary()`. Here is an example:
1416 You can also specify the string `all` to enable all logging.
1418 On macOS/iOS and Windows, each framework has its own individually supplied string that it uses to enable its own logging channels. On Linux, all frameworks share the same string.
1422 Set the `WEBKIT_DEBUG` environment variable.
1425 WEBKIT_DEBUG=Scrolling Tools/Scripts/run-minibrowser --gtk --debug
1430 On macOS, you can, for example, enable the `Language` log channel with these terminal commands:
1433 for identifier in com.apple.WebKit.WebContent.Development com.apple.WebKit.WebContent org.webkit.MiniBrowser com.apple.WebKit.WebKitTestRunner org.webkit.DumpRenderTree -g /Users/$USER/Library/Containers/com.apple.Safari/Data/Library/Preferences/com.apple.Safari.plist; do
1434 for key in WTFLogging WebCoreLogging WebKitLogging WebKit2Logging; do
1435 defaults write ${identifier} "${key}" "Language"
1440 You may also need to specify these strings to `com.apple.WebKit.WebContent.Development`, the global domain, or the Safari container, depending on what you're running.
1442 You may also pass this key and value as an argument:
1445 Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
1450 Set the `WebCoreLogging` environment variable.
1452 ## Adding a new log channel
1454 Simply add a line to your framework's `Logging.h` header. Depending on how the accompanying `Logging.cpp` file is set up, you may need to add a parallel line there. That should be all you need. It is acceptable to have log channels in different frameworks with the same name - this is what `LOG_CHANNEL_PREFIX` is for.