Modified: trunk/Introduction.md (290160 => 290161)
--- trunk/Introduction.md 2022-02-18 21:18:04 UTC (rev 290160)
+++ trunk/Introduction.md 2022-02-18 21:18:08 UTC (rev 290161)
@@ -7,7 +7,7 @@
The WebKit codebase is mostly written in C++ with bits of C and assembly, primarily in _javascript_Core, and some Objective-C to integrate with Cocoa platforms.
-It primarily consists of the following components, each inside its own directory in [Source](https://trac.webkit.org/browser/webkit/trunk/Source):
+It primarily consists of the following components, each inside its own directory in [Source](https://github.com/WebKit/WebKit/tree/main/Source):
* **bmalloc** - WebKit’s malloc implementation as a bump pointer allocator. It provides an important security feature, called IsoHeap,
which segregates each type of object into its own page to prevent type confusion attacks upon use-after-free.
@@ -155,7 +155,7 @@
Note that debugging WebCore code typically requires attaching to the relevant WebContent process,
-not the application process, which is mostly running code in [Source/WebKit/UIProcess](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/UIProcess).
+not the application process, which is mostly running code in [Source/WebKit/UIProcess](https://github.com/WebKit/WebKit/tree/main/Source/WebKit/UIProcess).
Depending on what you’re debugging, you’d have to attach & debug different processes in the coalition.
You may find it useful to use the debug helpers under `Tools/lldb/lldb_webkit.py`.
@@ -178,34 +178,34 @@
WebKit is really big on test driven development, we have many types of tests.
-* **_javascript_ tests** - Resides in top-level [JSTests](https://trac.webkit.org/browser/webkit/trunk/JSTests) directory.
+* **_javascript_ tests** - Resides in top-level [JSTests](https://github.com/WebKit/WebKit/tree/main/JSTests) directory.
This is the primary method of testing _javascript_Core. Use `Tools/Scripts/run-_javascript_core-tests` to run these tests.
-* **Layout tests** - Resides in top-level [LayoutTests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests) directory.
+* **Layout tests** - Resides in top-level [LayoutTests](https://github.com/WebKit/WebKit/tree/main/LayoutTests) directory.
This is the primary method of testing WebCore.
If you’re making code changes to WebCore, you typically run these tests. Use `Tools/Scripts/run-webkit-tests` to run these.
Pass `-1` to run tests using WebKitLegacy (a.k.a. WebKit1).
- [WebKitTestRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner) is used to run these tests for WebKit2,
- and [DumpRenderTree](https://trac.webkit.org/browser/webkit/trunk/Tools/DumpRenderTree) is used to these tests for WebKit1.
+ [WebKitTestRunner](https://github.com/WebKit/WebKit/tree/main/Tools/WebKitTestRunner) is used to run these tests for WebKit2,
+ and [DumpRenderTree](https://github.com/WebKit/WebKit/tree/main/Tools/DumpRenderTree) is used to these tests for WebKit1.
There are a few styles of layout tests but all of them have a test file and expected result (ends with -expected.txt),
and the test passes if the test file’s output matches that of the expected result.
-* **API tests** - Reside in [Tools/TestWebKitAPI](https://trac.webkit.org/browser/webkit/trunk/Tools/TestWebKitAPI),
+* **API tests** - Reside in [Tools/TestWebKitAPI](https://github.com/WebKit/WebKit/tree/main/Tools/TestWebKitAPI),
these are [GTests](https://en.wikipedia.org/wiki/Google_Test) that test APIs exposed by _javascript_Core,
WebKitLegacy, and WebKit layers as well as unit tests for selected WTF classes.
WebKit does not use [XCTests](https://developer.apple.com/documentation/xctest).
Use `Tools/Scripts/run-api-tests` to run these tests.
Because these API tests are sequentially, it’s preferable to write layout tests when possible.
-* **Bindings tests** - Reside in [Source/WebCore/bindings/scripts/test](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/scripts/test),
+* **Bindings tests** - Reside in [Source/WebCore/bindings/scripts/test](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/bindings/scripts/test),
these are tests for WebCore’s binding code generator.
Use `Tools/Scripts/run-bindings-tests` to run these tests.
-* **webkitpy tests** - Tests for WebKit’s various Python scripts in [Tools/Scripts/webkitpy](https://trac.webkit.org/browser/webkit/trunk/Tools/Scripts/webkitpy).
+* **webkitpy tests** - Tests for WebKit’s various Python scripts in [Tools/Scripts/webkitpy](https://github.com/WebKit/WebKit/tree/main/Tools/Scripts/webkitpy).
Use `Tools/Scripts/test-webkitpy` to run these tests.
-* **webkitperl tests** - Tests for WebKit’s various Perl scripts in [Tools/Scripts/webkitperl](https://trac.webkit.org/browser/webkit/trunk/Tools/Scripts/webkitperl).
+* **webkitperl tests** - Tests for WebKit’s various Perl scripts in [Tools/Scripts/webkitperl](https://github.com/WebKit/WebKit/tree/main/Tools/Scripts/webkitperl).
Use `Tools/Scripts/test-webkitperl` to run these tests.
## Performance Testing in WebKit
The WebKit project has a "no performance regression" policy.
-We maintain the performance of the following of the benchmarks and are located under [PerformanceTests](https://trac.webkit.org/browser/webkit/trunk/PerformanceTests).
+We maintain the performance of the following of the benchmarks and are located under [PerformanceTests](https://github.com/WebKit/WebKit/tree/main/PerformanceTests).
If your patch regresses one of these benchmarks even slightly (less than 1%), it will get reverted.
* **JetStream2** - Measures _javascript_ and WASM performance.
@@ -245,7 +245,7 @@
### Licensing
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).
-New code contributed to WebKit will use the [two clause BSD license](https://trac.webkit.org/browser/trunk/Source/WebCore/LICENSE-APPLE).
+New code contributed to WebKit will use the [two clause BSD license](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/LICENSE-APPLE).
When contributing new code, update the copyright date.
When moving the existing code, you need to include the original copyright notice for the moved code
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.
@@ -334,7 +334,7 @@
Make sure to uncheck the target membership so that it’s not compiled as a part of the framework in xcodebuild.
Instead, add the same file in Sources.txt file that exists in each subdirectory of Source.
-e.g. [Source/WebCore/Sources.txt](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/Sources.txt) for WebCore.
+e.g. [Source/WebCore/Sources.txt](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Sources.txt) for WebCore.
This will ensure the newly added file is compiled as a part of *unified sources*.
When a header file in WTF is used in WebCore, or a header file in WebCore is used in WebKit or WebKitLegacy,
@@ -439,8 +439,8 @@
Most of WebCore objects are not managed by _javascript_Core’s garbage collector.
Instead, we use [reference counting](https://en.wikipedia.org/wiki/Reference_counting).
We have two referencing counting pointer types:
-[`RefPtr`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/RefPtr.h)
-and [`Ref`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/Ref.h).
+[`RefPtr`](https://github.com/WebKit/WebKit/blob/main/Source/WTF/wtf/RefPtr.h)
+and [`Ref`](https://github.com/WebKit/WebKit/blob/main/Source/WTF/wtf/Ref.h).
RefPtr is intended to behave like a C++ pointer whereas Ref is intended to behave like a C++ reference,
meaning that the former can be set to `nullptr` but the latter cannot.
@@ -466,7 +466,7 @@
* When `deref()` is called when its internal reference counter reaches 0, “this” object is destructed and deleted.
There is a convenience super template class,
-[`RefCounted<T>`](https://trac.webkit.org/browser/webkit/trunk/Source/WTF/wtf/RefCounted.h),
+[`RefCounted<T>`](https://github.com/WebKit/WebKit/blob/main/Source/WTF/wtf/RefCounted.h),
which implements this behavior for any inherited class T automatically.
### How to use RefPtr and Ref
@@ -593,7 +593,7 @@
a function that operates on a node of such a tree data structure can end up deleting itself (`this` object).
This is highly undesirable as such code often ends up having a use-after-free bug.
-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):
+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://github.com/WebKit/WebKit/blob/ea1a56ee11a26f292f3d2baed2a3aea95fea40f1/Source/WebCore/dom/ContainerNode.cpp#L632):
```cpp
ExceptionOr<void> ContainerNode::removeChild(Node& oldChild)
@@ -608,7 +608,7 @@
if (oldChild.parentNode() != this)
return Exception { NotFoundError };
- if (!removeNodeWithScriptAssertion(oldChild, ChildChangeSource::API))
+ if (!removeNodeWithScriptAssertion(oldChild, ChildChange::Source::API))
return Exception { NotFoundError };
rebuildSVGExtensionsElementsIfNecessary();
@@ -622,10 +622,10 @@
As a result, `rebuildSVGExtensionsElementsIfNecessary` or `dispatchSubtreeModifiedEvent` might be called
after `this` object had already been free’ed if we didn’t have `protectedThis`,
which guarantees that this object’s reference count is at least 1
-(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).
+(because [Ref’s constructor](https://github.com/WebKit/WebKit/blob/ea1a56ee11a26f292f3d2baed2a3aea95fea40f1/Source/WTF/wtf/Ref.h#L64) increments the reference count by 1).
This pattern can be used for other objects that need to be *protected* from destruction inside a code block.
-In the [following code](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/ContainerNode.cpp?rev=251041#L123),
+In the [following code](https://github.com/WebKit/WebKit/blob/ea1a56ee11a26f292f3d2baed2a3aea95fea40f1/Source/WebCore/dom/ContainerNode.cpp#L162),
`childToRemove` was passed in using C++ reference.
Because this function is going to remove this child node from `this` container node,
it can get destructed while the function is still running.
@@ -707,19 +707,19 @@
Broadly speaking, DOM node divides into the following categories:
-* [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).
-* 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).
+* [Container nodes](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/ContainerNode.h) such as [Document](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Document.h), [Element](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Element.h), and [DocumentFragment](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/DocumentFragment.h).
+* Leaf nodes such as [DocumentType](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/DocumentType.h), [Text](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Text.h), and [Attr](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Attr.h).
-[Document](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Document.h) node,
+[Document](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Document.h) node,
as the name suggests a single HTML, SVG, MathML, or other XML document,
-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.
+and is the [owner](https://github.com/WebKit/WebKit/blob/ea1a56ee11a26f292f3d2baed2a3aea95fea40f1/Source/WebCore/dom/Node.h#L359) of every node in the document.
It is the very first node in any document that gets created and the very last node to be destroyed.
-Note that a single web [page](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/Page.h) may consist of multiple documents
+Note that a single web [page](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/page/Page.h) may consist of multiple documents
since [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
and [object](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object) elements may contain
-a child [frame](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/Frame.h),
-and form a [frame tree](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/page/FrameTree.h).
+a child [frame](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/page/Frame.h),
+and form a [frame tree](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/page/FrameTree.h).
Because _javascript_ can [open a new window](https://developer.mozilla.org/en-US/docs/Web/API/Window/open)
under user gestures and have [access back to its opener](https://developer.mozilla.org/en-US/docs/Web/API/Window/opener),
multiple web pages across multiple tabs might be able to communicate with one another via _javascript_ API
@@ -730,20 +730,20 @@
Each DOM node’s behavior is implemented as a C++ class in WebCore.
_javascript_ API is primarily implemented using [Web IDL](https://heycam.github.io/webidl/),
an [interface description language](https://en.wikipedia.org/wiki/Interface_description_language),
-from which various [JS DOM binding code](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings)
-is auto-generated by a [perl script](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/scripts/CodeGeneratorJS.pm),
+from which various [JS DOM binding code](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/bindings)
+is auto-generated by a [perl script](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/scripts/CodeGeneratorJS.pm),
for example, under `WebKitBuild/Debug/DerivedSources/WebCore/` for debug builds.
For example, C++ implementation of [Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)
-is [Node class](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Node.h)
+is [Node class](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Node.h)
and its _javascript_ interface is implemented by JSNode class,
most of which is auto-generated but has some custom bindings code in
-[JSNodeCustom](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSNodeCustom.cpp).
+[JSNodeCustom](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/js/JSNodeCustom.cpp).
Similarly, C++ implementation of [Range interface](https://developer.mozilla.org/en-US/docs/Web/API/Range)
-is [Range class](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Range.h)
+is [Range class](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Range.h)
whilst its _javascript_ API is implemented by the auto-generated JSRange class.
We call instances of the latter JS* classes *JS wrappers*.
-These JS wrappers exist in what we call a [`DOMWrapperWorld`](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/DOMWrapperWorld.h).
+These JS wrappers exist in what we call a [`DOMWrapperWorld`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/js/DOMWrapperWorld.h).
Each `DOMWrapperWorld` has its own JS wrapper for each C++ object.
As a result, a single C++ object may have multiple JS wrappers in distinct `DOMWrapperWorld`s.
The most important `DOMWrapperWorld` is the main `DOMWrapperWorld` which runs the scripts of web pages WebKit loaded
@@ -752,21 +752,21 @@
JSX.h provides `toJS` functions which creates a JS wrapper for X
in a given [global object](https://developer.mozilla.org/en-US/docs/Glossary/Global_object)’s `DOMWrapperWorld`,
and toWrapped function which returns the underlying C++ object.
-For example, `toJS` function for [Node](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/dom/Node.h)
-is defined in [Source/WebCore/bindings/js/JSNodeCustom.h](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSNodeCustom.h).
+For example, `toJS` function for [Node](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Node.h)
+is defined in [Source/WebCore/bindings/js/JSNodeCustom.h](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/js/JSNodeCustom.h).
When there is already a JS wrapper object for a given C++ object,
`toJS` function will find the appropriate JS wrapper in
-a [hash map](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/DOMWrapperWorld.h?rev=251425#L53)
+a [hash map](https://github.com/WebKit/WebKit/blob/ea1a56ee11a26f292f3d2baed2a3aea95fea40f1/Source/WebCore/bindings/js/DOMWrapperWorld.h#L74)
of the given `DOMWrapperWorld`.
Because a hash map lookup is expensive, some WebCore objects will inherit from
-[ScriptWrappable](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/ScriptWrappable.h),
+[ScriptWrappable](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/js/ScriptWrappable.h),
which has an inline pointer to the JS wrapper for the main world if one was already created.
## JS Wrapper Lifecycle Management
As a general rule, a JS wrapper object keeps its underlying C++ object alive by means of reference counting
-in [JSDOMWrapper](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/bindings/js/JSDOMWrapper.h) temple class
+in [JSDOMWrapper](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/bindings/js/JSDOMWrapper.h) temple class
from which all JS wrappers in WebCore inherits.
However, **C++ objects do not keep their corresponding JS wrapper in each world alive** by the virtue of them staying alive
as such a circular dependency will result in a memory leak.
@@ -840,9 +840,9 @@
### Directory Structure
-[LayoutTests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests) directory is organized by the category of tests.
-For example, [LayoutTests/accessibility](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/accessibility) contains accessibility related tests,
-and [LayoutTests/fast/dom/HTMLAnchorElement](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/HTMLAnchorElement) contains
+[LayoutTests](https://github.com/WebKit/WebKit/tree/main/LayoutTests) directory is organized by the category of tests.
+For example, [LayoutTests/accessibility](https://github.com/WebKit/WebKit/tree/main/LayoutTests/accessibility) contains accessibility related tests,
+and [LayoutTests/fast/dom/HTMLAnchorElement](https://github.com/WebKit/WebKit/tree/main/LayoutTests/fast/dom/HTMLAnchorElement) contains
tests for [the HTML anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a).
Any file that ends in `.html`, `.htm`, `.shtml`, `.xhtml`, `.mht`, `.xht`, `.xml`, `.svg`, or `.php` is considered as a test
@@ -853,11 +853,11 @@
and it is compared against these expected results.
In the case expected results may differ from one platform to another,
-the expected results for each test is stored in [LayoutTests/platform](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform).
+the expected results for each test is stored in [LayoutTests/platform](https://github.com/WebKit/WebKit/tree/main/LayoutTests/platform).
The expected result of a given test exists in the corresponding directory in
-each subdirectory of [LayoutTests/platform](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform).
-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)
-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).
+each subdirectory of [LayoutTests/platform](https://github.com/WebKit/WebKit/tree/main/LayoutTests/platform).
+For example, the expected result of [LayoutTests/svg/W3C-SVG-1.1/animate-elem-46-t.svg](https://github.com/WebKit/WebKit/blob/main/LayoutTests/svg/W3C-SVG-1.1/animate-elem-46-t.svg)
+for macOS Mojave is located at [LayoutTests/platform/mac-mojave/svg/W3C-SVG-1.1/animate-elem-46-t-expected.txt](https://github.com/WebKit/WebKit/blob/main/LayoutTests/platform/mac-mojave/svg/W3C-SVG-1.1/animate-elem-46-t-expected.txt).
These platform directories have a fallback order.
For example, running tests for WebKit2 on macOS Catalina will use the following fallback path from the most specific to most generic:
@@ -871,11 +871,11 @@
### Imported Tests
-Tests under [LayoutTests/imported](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported) are imported from other repositories.
+Tests under [LayoutTests/imported](https://github.com/WebKit/WebKit/tree/main/LayoutTests/imported) are imported from other repositories.
**They should not be modified by WebKit patches** unless the change is made in respective repositories first.
Most notable is [Web Platform Tests](https://web-platform-tests.org/),
-which are imported under [LayoutTests/imported/w3c/web-platform-tests](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/imported/w3c/web-platform-tests).
+which are imported under [LayoutTests/imported/w3c/web-platform-tests](https://github.com/WebKit/WebKit/tree/main/LayoutTests/imported/w3c/web-platform-tests).
These are cross browser vendor tests developed by W3C. Mozilla, Google, and Apple all contribute many tests to this shared test repository.
### HTTP Tests
@@ -961,7 +961,7 @@
This is the oldest style of layout tests, and the default mode of layout tests.
It’s a text serialization of WebKit’s render tree and its output looks like
-[this](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/platform/mac/fast/dom/anchor-text-expected.txt):
+[this](https://github.com/WebKit/WebKit/blob/main/LayoutTests/platform/mac/fast/dom/anchor-text-expected.txt):
```
layer at (0,0) size 800x600
@@ -995,7 +995,7 @@
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).
All these tests call `testRunner.dumpAsText` to trigger this behavior.
The output typically contains a log of text or other informative output scripts in the page produced.
-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:
+For example, [LayoutTests/fast/dom/anchor-toString.html](https://github.com/WebKit/WebKit/blob/main/LayoutTests/fast/dom/anchor-toString.html) is written as follows:
```html
<a href="" id="anchor">
@@ -1020,7 +1020,7 @@
</script>
```
- and generates the following [output](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/anchor-toString-expected.txt):
+ and generates the following [output](https://github.com/WebKit/WebKit/blob/main/LayoutTests/fast/dom/anchor-toString-expected.txt):
```
A link!
@@ -1035,14 +1035,14 @@
### js-test.js and js-test-pre.js tests
These are variants of dumpAsText test which uses WebKit’s assertion library:
-[LayoutTests/resources/js-test.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test.js)
-and [LayoutTests/resources/js-test-pre.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/js-test-pre.js).
+[LayoutTests/resources/js-test.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/js-test.js)
+and [LayoutTests/resources/js-test-pre.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/js-test-pre.js).
It consists of shouldX function calls which takes two _javascript_ code snippet which are then executed and outputs of which are compared.
js-test.js is simply a new variant of js-test-pre.js that doesn’t require
-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.
+the inclusion of [LayoutTests/resources/js-test-post.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/js-test-post.js) at the end.
**Use js-test.js in new tests**, not js-test-pre.js.
-For example, [LayoutTests/fast/dom/Comment/remove.html](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/Comment/remove.html)
+For example, [LayoutTests/fast/dom/Comment/remove.html](https://github.com/WebKit/WebKit/blob/main/LayoutTests/fast/dom/Comment/remove.html)
which tests [remove()](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove) method
on [Comment node](https://developer.mozilla.org/en-US/docs/Web/API/Comment) is written as:
@@ -1067,7 +1067,7 @@
<script src=""
```
-with the following [expected result](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/fast/dom/Comment/remove-expected.txt) (output):
+with the following [expected result](https://github.com/WebKit/WebKit/blob/main/LayoutTests/fast/dom/Comment/remove-expected.txt) (output):
```
This tests the DOM 4 remove method on a Comment.
@@ -1088,7 +1088,7 @@
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.
-[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.
+[js-test.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/js-test.js) and [js-test-pre.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/js-test-pre.js) provide all kinds of other assertion and helper functions.
Here are some examples:
* `debug(msg)` - Inserts a debug / log string in the output.
@@ -1100,13 +1100,13 @@
* `shouldBeNull(code)` - Shorthand for `shouldBe(code, 'null')`.
* `shouldBeZero(code)` - Shorthand for `shouldBe(code, '0')`.
* `shouldBeEqualToString(code, string)` - Similar to `shouldBe` but the second argument is not evaluated as string.
-* `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).
+* `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://github.com/WebKit/WebKit/blob/main/LayoutTests/fast/dom/iframe-innerWidth.html).
**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.**
Another way to think about this is that `-expected.txt` files are baseline outputs, and baseline outputs can contain known failures.
-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):
+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://github.com/WebKit/WebKit/tree/main/LayoutTests/fast/dom):
```sh
Tools/Scripts/make-new-script-test fast/dom/new-test.html
@@ -1115,9 +1115,9 @@
### dump-as-markup.js Tests
A dump-as-markup.js test is yet another variant of dumpAsText test,
-which uses [LayoutTests/resources/dump-as-markup.js](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/resources/dump-as-markup.js).
+which uses [LayoutTests/resources/dump-as-markup.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/dump-as-markup.js).
This style of test is used when it’s desirable to compare the state of the DOM tree before and after some operations.
-For example, many tests under [LayoutTests/editing](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/editing)
+For example, many tests under [LayoutTests/editing](https://github.com/WebKit/WebKit/tree/main/LayoutTests/editing)
use this style of testing to test complex DOM mutation operations such as pasting HTML from the users’ clipboard.
dump-as-markup.js adds `Markup` on the global object and exposes a few helper functions.
Like js-test.js tests, a test description can be specified via `Markup.description`.
@@ -1125,7 +1125,7 @@
where `element` is either a DOM [node](https://developer.mozilla.org/en-US/docs/Web/API/Node)
under which the state should be serialized or its [id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
-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:
+For example, [LayoutTests/editing/inserting/insert-list-in-table-cell-01.html](https://github.com/WebKit/WebKit/blob/main/LayoutTests/editing/inserting/insert-list-in-table-cell-01.html) is written as follows:
```html
<!DOCTYPE html>
@@ -1144,7 +1144,7 @@
</script>
```
-with the following [expected result](https://trac.webkit.org/browser/webkit/trunk/LayoutTests/editing/inserting/insert-list-in-table-cell-01-expected.txt):
+with the following [expected result](https://github.com/WebKit/WebKit/blob/main/LayoutTests/editing/inserting/insert-list-in-table-cell-01-expected.txt):
```
Insert list items in a single table cell:
@@ -1191,7 +1191,7 @@
which is [W3C](https://www.w3.org/)’s official tests for the Web.
There is an [extensive documentation](https://web-platform-tests.org/writing-tests/testharness-api.html) on how this harness works.
-> 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)
+> As mentioned above, do not modify tests in [LayoutTests/imported/w3c/web-platform-tests](https://github.com/WebKit/WebKit/tree/main/LayoutTests/imported/w3c/web-platform-tests)
unless the same test changes are made in Web Platform Tests’ primary repository.
### Reference Tests
@@ -1209,35 +1209,23 @@
* The file specified by a HTML link element in the test file with `match` relation: `<link rel=match href="" where X is the relative file path is a matching expected result.
* The file specified by a HTML link element in the test file with `mismatch` relation: `<link rel=mismatch href="" where X is the relative file path is a mismatching expected result.
-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:
+For example, [LayoutTests/imported/w3c/web-platform-tests/html/rendering/replaced-elements/images/space.html](https://github.com/WebKit/WebKit/blob/main/LayoutTests/imported/w3c/web-platform-tests/html/rendering/replaced-elements/images/space.html) specifies [space-ref.html](https://github.com/WebKit/WebKit/blob/main/LayoutTests/imported/w3c/web-platform-tests/html/rendering/replaced-elements/images/space-ref.html) in the same directory as the matching expected result as follows:
```html
-<!DOCTYPE html>
+<!doctype html>
<meta charset=utf-8>
-<link rel=match href=""
+<title>img hspace/vspace</title>
+<link rel=match href=""
<style>
- html, body {
- margin: 0;
- padding: 0;
- }
+span { background: blue; }
</style>
-<canvas id="c" width="150" height="150" >
-Your browser does not support the HTML5 canvas tag.</canvas>
-
-<script>
-var c = document.getElementById("c");
-var ctx = c.getContext("2d");
-
-ctx.beginPath();
-ctx.moveTo(20, 20);
-ctx.lineTo(20, 130);
-ctx.lineTo(130, 130);
-ctx.lineTo(130, 20);
-ctx.closePath();
-
-ctx.fillStyle = '#90EE90';
-ctx.fill();
-</script>
+<div style=width:400px;>
+<p><span><img src=""
+<p><span><img src="" hspace=10></span>
+<p><span><img src="" vspace=10></span>
+<p><span><img src="" hspace=10%></span>
+<p><span><img src="" vspace=10%></span>
+</div>
```
## Test Runners
@@ -1244,8 +1232,8 @@
Most layout tests are designed to be runnable inside a browser but run-webkit-tests uses a special program to run them.
Our continuous integration system as well as the Early Warning System uses run-webkit-tests to run layout tests.
-In WebKit2, this is appropriately named [WebKitTestRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner).
-In WebKit1 or WebKitLegacy, it’s [DumpRenderTree](https://trac.webkit.org/browser/webkit/trunk/Tools/DumpRenderTree),
+In WebKit2, this is appropriately named [WebKitTestRunner](https://github.com/WebKit/WebKit/tree/main/Tools/WebKitTestRunner).
+In WebKit1 or WebKitLegacy, it’s [DumpRenderTree](https://github.com/WebKit/WebKit/tree/main/Tools/DumpRenderTree),
which is named after the very first type of layout tests, which generated the text representation of the render tree.
### Extra Interfaces Available in Test Runners
@@ -1253,10 +1241,10 @@
Both WebKitTestRunner and DumpRenderTree expose a few extra interfaces to _javascript_ on `window` (i.e. global object) in order to emulate user inputs,
enable or disable a feature, or to improve the reliability of testing.
-* **[GCController](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/GCController.idl)**
+* **[GCController](https://github.com/WebKit/WebKit/blob/main/Tools/WebKitTestRunner/InjectedBundle/Bindings/GCController.idl)**
- `GCController.collect()` triggers a synchronous full garbage collection.
This function is useful for testing crashes or erroneous premature collection of JS wrappers and leaks.
-* **[testRunner](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/TestRunner.idl)**
+* **[testRunner](https://github.com/WebKit/WebKit/blob/main/Tools/WebKitTestRunner/InjectedBundle/Bindings/TestRunner.idl)**
- TestRunner interface exposes many methods to control the behaviors of WebKitTestRunner and DumpRenderTree.
Some the most commonly used methods are as follows:
* `waitUntilDone()` / `notifyDone()` - These functions are useful when writing tests that involve asynchronous tasks
@@ -1264,30 +1252,28 @@
`testRunner.waitUntilDone()` makes WebKitTestRunner and DumpRenderTree not end the test when a layout test has finished loading.
The test continues until `testRunner.notifyDone()` is called.
* `dumpAsText(boolean dumpPixels)` - Makes WebKitTestRunner and DumpRenderTree output the plain text of the loaded page instead of the state of the render tree.
- * `overridePreference(DOMString preference, DOMString value)` - Overrides WebKit’s preferences.
- For WebKit2, these preferences are defined in [Source/WebKit/Shared/WebPreferences.yaml](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/Shared/WebPreferences.yaml).
- 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
- and [Source/WebKitLegacy/win/WebPreferences.h](https://trac.webkit.org/browser/webkit/trunk/Source/WebKitLegacy/win/WebPreferences.h) for Windows.
-* **[eventSender](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/EventSendingController.idl)**
+ * `overridePreference(DOMString preference, DOMString value)` - Overrides WebKit’s [preferences](https://github.com/WebKit/WebKit/tree/main/Source/WTF/Scripts/Preferences).
+ For WebKitLegacy, these are defined in [Source/WebKitLegacy/mac/WebView/WebPreferences.h](https://github.com/WebKit/WebKit/tree/main/Source/WebKitLegacy/mac/WebView/WebPreferences.h) for macOS
+ and [Source/WebKitLegacy/win/WebPreferences.h](https://github.com/WebKit/WebKit/tree/main/Source/WebKitLegacy/win/WebPreferences.h) for Windows.
+* **[eventSender](https://github.com/WebKit/WebKit/blob/main/Tools/WebKitTestRunner/InjectedBundle/Bindings/EventSendingController.idl)**
- Exposes methods to emulate mouse, keyboard, and touch actions.
- **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.
+ **Use [ui-helpers.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/ui-helper.js) script** instead of directly calling methods on this function.
This will ensure the test will be most compatible with all the test configurations we have.
-* [**UIScriptController**](https://trac.webkit.org/browser/webkit/trunk/Tools/TestRunnerShared/UIScriptContext/Bindings/UIScriptController.idl)
+* [**UIScriptController**](https://github.com/WebKit/WebKit/tree/main/Tools/TestRunnerShared/UIScriptContext/Bindings/UIScriptController.idl)
- Exposes methods to emulate user inputs like eventSender mostly on iOS WebKit2.
- **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.
+ **Use [ui-helpers.js](https://github.com/WebKit/WebKit/blob/main/LayoutTests/resources/ui-helper.js) script** instead of directly calling methods on this function.
This will ensure the test will be most compatible with all the test configurations we have.
-* **[textInputController](https://trac.webkit.org/browser/webkit/trunk/Tools/WebKitTestRunner/InjectedBundle/Bindings/TextInputController.idl)**
+* **[textInputController](https://github.com/WebKit/WebKit/blob/main/Tools/WebKitTestRunner/InjectedBundle/Bindings/TextInputController.idl)**
- Exposes methods to test [input methods](https://en.wikipedia.org/wiki/Input_method).
-Additionally, [WebCore/testing](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing) exposes a few testing hooks to test its internals:
+Additionally, [WebCore/testing](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/testing) exposes a few testing hooks to test its internals:
-* **[internals](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing/Internals.idl)**
+* **[internals](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/testing/Internals.idl)**
- Exposes various hooks into WebCore that shouldn’t be part of WebKit or WebKitLegacy API.
-* [**internals.settings**](https://trac.webkit.org/browser/webkit/trunk/Source/WebCore/testing/InternalSettings.idl)
+* [**internals.settings**](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/testing/InternalSettings.idl)
- Exposes various WebCore settings and let tests override them.
- Note that WebKit layer code depends on [Source/WebKit/Shared/WebPreferences.yaml](https://trac.webkit.org/browser/webkit/trunk/Source/WebKit/Shared/WebPreferences.yaml),
- and will not respect this override.
- Because of this, it’s preferable to override the equivalent preference via `testRunner.overridePreference`
+ Note that WebKit layer code may depend on preferences in UI process and the aforementioned `testRunner.overridePreference` may need to be used instead.
+ It’s in fact preferable to override the equivalent preference via `testRunner.overridePreference`
unless you know for sure WebKit or WebKitLegacy layer of code isn’t affected by the setting you’re overriding.
### Enabling or Disabling a Feature in Test Runners
@@ -1335,7 +1321,7 @@
You may find Xcode fails to attach to WebContent or Networking process in the case of WebKitTestRunner.
In those cases, attach a breakpoint in UIProcess code
-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).
+such as [`TestController::runTest` in WebKitTestRunner right before `TestInvocation::invoke` is called](https://github.com/WebKit/WebKit/blob/5f4c01f41527547ce2f82b812ad478e12b51239d/Tools/WebKitTestRunner/TestController.cpp#L1522).
Once breakpoint is hit in the UIProcess, attach to `WebContent.Development` or `Networking.Development` process manually in Xcode via Debug > Attach to Process.
# Dive into API tests
