= 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.