What is an abandoned document?

Abandoned documents are effectively leaked: they are Document objects which have never been destroyed, and persist after loading about:blank, running a garbage collection and clearing caches. This is probably because there's some object that is holding a reference to the Document object, possibly in the GC heap, or via a retain cycle (often involving Nodes in the document).

All documents are referenced by Document::allDocumentsMap(), so they are not leaked in the sense that the 'leaks' tool doesn't show them.

Why are layout test results showing me a list of abandoned documents?

Leaked documents usually entrain a lot of other objects, which can use lots of memory (e.g. via entries in the memory cache). Leaking documents is bad because it will cause ever-increasing memory use as the user browses. See ​https://bugs.webkit.org/show_bug.cgi?id=186214

What should I do if see a new case of document abandonment?

If you made a code change that is causing a test to newly show that a document is leaked, it probably means you have a coding bug that is triggered a leak or (more likely) a reference cycle. You need to resolve this before committing.

How do I debug document abandonment?

Let's take an example ​https://bugs.webkit.org/show_bug.cgi?id=188722. We run tests, checking for abandonment:

run-webkit-tests fast/forms/ --check-for-abandoned-documents

The results say that fast/forms/textarea-paste-newline.html was abandoned. Now you have to figure out why this Document object is not going away.

A bit of testing in MiniBrowser can be useful, and if you're lucky, the abandonment will reproduce there. To test this, do these steps:

1. Run MiniBrowser
2. Load a simple HTML file (not the test!)
3. Load the test file
4. Go back to the simple HTML file
5. Simulate a memory warning (on macOS, you can do this by running notifyutil -p "org.WebKit.lowMemory" in the Terminal).
6. Now dump the list of live documents: notifyutil -p "com.apple.WebKit.showAllDocuments". This will show something like:

   2 live documents:
   Document 0x630002400 (refCount 5, referencingNodeCount 1) file:///Volumes/Data/webkit/LayoutTests/fast/forms/textarea-paste-newline.html
   Document 0x630024400 (refCount 2, referencingNodeCount 4) file:///Volumes/Data/simple.html
   

7. That confirms that after a memory warning (which clears caches and does a GC) that the document is still alive. So something is holding a reference to it.