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.
8. Now you could start doing manual debugging of ref() and deref() to try to figure out where the extra ref() is happening. But there's a better way.
   1. Apply the most recent patch from ​https://bugs.webkit.org/show_bug.cgi?id=186269 (if this has not been checked in yet) and build.
   2. Repeat the above steps. Now the output will be something like:

      2 live documents:
      Document 0x630002400 (refCount 5, referencingNodeCount 1) file:///Volumes/Data/Development/apple/webkit/OpenSource/LayoutTests/fast/forms/textarea-paste-newline.html
      Document 0x630002400 reference stacks:
      Backtrace for token 6074
      1   0x6179baa97 WebCore::Node::ref()
      2   0x615af576e unsigned int WTF::refIfNotNull<WebCore::Node>(WebCore::Node*)
      3   0x615af5728 WTF::RefPtr<WebCore::Node, WTF::DumbPtrTraits<WebCore::Node> >::RefPtr(WebCore::Node*)
      4   0x615af4add WTF::RefPtr<WebCore::Node, WTF::DumbPtrTraits<WebCore::Node> >::RefPtr(WebCore::Node*)
      5   0x615af4b73 WTF::RefPtr<WebCore::Node, WTF::DumbPtrTraits<WebCore::Node> >::operator=(WebCore::Node*)
      6   0x61788ccb2 WebCore::Document::removeFocusNavigationNodeOfSubtree(WebCore::Node&, bool)
      7   0x61788c82a WebCore::Document::nodeChildrenWillBeRemoved(WebCore::ContainerNode&)
      8   0x6178252de WebCore::ContainerNode::removeAllChildrenWithScriptAssertion(WebCore::ContainerNode::ChildChangeSource, WebCore::ContainerNode::DeferChildrenChanged)
      9   0x617828d49 WebCore::ContainerNode::removeChildren()
      10  0x617882aef WebCore::Document::implicitOpen()
      11  0x617878043 WebCore::Document::open(WebCore::Document*)
      12  0x617884062 WebCore::Document::write(WebCore::Document*, WebCore::SegmentedString&&)
      13  0x61788432b WebCore::Document::write(WebCore::Document*, WTF::Vector<WTF::String, 0ul, WTF::CrashOnOverflow, 16ul>&&)
      14  0x61609d242 WebCore::jsDocumentPrototypeFunctionWriteBody(JSC::ExecState*, WebCore::JSDocument*, JSC::ThrowScope&)
      15  0x61608046e long long WebCore::IDLOperation<WebCore::JSDocument>::call<&(WebCore::jsDocumentPrototypeFunctionWriteBody(JSC::ExecState*, WebCore::JSDocument*, JSC::ThrowScope&)), (WebCore::CastedThisErrorBehavior)0>(JSC::ExecState&, char const*)
      16  0x61608016c WebCore::jsDocumentPrototypeFunctionWrite(JSC::ExecState*)
      17  0xeef1324177
      18  0x62650d44b llint_entry
      19  0x62650d44b llint_entry
      20  0x626504e37 vmEntryToJavaScript
      21  0x6270a7c7a JSC::JITCode::execute(JSC::VM*, JSC::ProtoCallFrame*)
      22  0x6270a8303 JSC::Interpreter::executeCall(JSC::ExecState*, JSC::JSObject*, JSC::CallType, JSC::CallData const&, JSC::JSValue, JSC::ArgList const&)
      23  0x627356dce JSC::call(JSC::ExecState*, JSC::JSValue, JSC::CallType, JSC::CallData const&, JSC::JSValue, JSC::ArgList const&)
      24  0x627356eac JSC::call(JSC::ExecState*, JSC::JSValue, JSC::CallType, JSC::CallData const&, JSC::JSValue, JSC::ArgList const&, WTF::NakedPtr<JSC::Exception>&)
      25  0x62735717d JSC::profiledCall(JSC::ExecState*, JSC::ProfilingReason, JSC::JSValue, JSC::CallType, JSC::CallData const&, JSC::JSValue, JSC::ArgList const&, WTF::NakedPtr<JSC::Exception>&)
      26  0x617351ffb WebCore::JSExecState::profiledCall(JSC::ExecState*, JSC::ProfilingReason, JSC::JSValue, JSC::CallType, JSC::CallData const&, JSC::JSValue, JSC::ArgList const&, WTF::NakedPtr<JSC::Exception>&)
      27  0x617398407 WebCore::JSEventListener::handleEvent(WebCore::ScriptExecutionContext&, WebCore::Event&)
      28  0x617960d3e WebCore::EventTarget::fireEventListeners(WebCore::Event&, WTF::Vector<WTF::RefPtr<WebCore::RegisteredEventListener, WTF::DumbPtrTraits<WebCore::RegisteredEventListener> >, 1ul, WTF::CrashOnOverflow, 16ul>)
      29  0x61795c7a0 WebCore::EventTarget::fireEventListeners(WebCore::Event&)
      30  0x61824752d WebCore::DOMWindow::dispatchEvent(WebCore::Event&, WebCore::EventTarget*)
      31  0x6182523de WebCore::DOMWindow::dispatchLoadEvent()
      32  0x6178839fa WebCore::Document::dispatchWindowLoadEvent()
      33  0x61787bff3 WebCore::Document::implicitClose()
      34  0x6180d6f2b WebCore::FrameLoader::checkCallImplicitClose()
      35  0x6180d69c8 WebCore::FrameLoader::checkCompleted()
      36  0x6180d58f5 WebCore::FrameLoader::finishedParsing()
      37  0x617895ca9 WebCore::Document::finishedParsing()
      38  0x617e3df58 WebCore::HTMLConstructionSite::finishedParsing()
      39  0x617e8c969 WebCore::HTMLTreeBuilder::finished()
      40  0x617e4708c WebCore::HTMLDocumentParser::end()
      41  0x617e440e9 WebCore::HTMLDocumentParser::attemptToRunDeferredScriptsAndEnd()
      42  0x617e43de3 WebCore::HTMLDocumentParser::prepareToStopParsing()
      43  0x617e470ff WebCore::HTMLDocumentParser::attemptToEnd()
      44  0x617e471d8 WebCore::HTMLDocumentParser::finish()
      45  0x6180c55fe WebCore::DocumentWriter::end()
      46  0x618084a1f WebCore::DocumentLoader::finishedLoading()
      47  0x6180847bf WebCore::DocumentLoader::notifyFinished(WebCore::CachedResource&)
      48  0x6181c7fdf WebCore::CachedResource::checkNotify()
      49  0x6181ba091 WebCore::CachedResource::finishLoading(WebCore::SharedBuffer*)
      50  0x6181c4ec2 WebCore::CachedRawResource::finishLoading(WebCore::SharedBuffer*)
      51  0x618155a58 WebCore::SubresourceLoader::didFinishLoading(WebCore::NetworkLoadMetrics const&)
      52  0x610f6d50b WebKit::WebResourceLoader::didFinishResourceLoad(WebCore::NetworkLoadMetrics const&)
      53  0x610f71b8a void IPC::callMemberFunctionImpl<WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>, 0ul>(WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>&&, std::__1::integer_sequence<unsigned long, 0ul>)
      54  0x610f71a10 void IPC::callMemberFunction<WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>, std::__1::integer_sequence<unsigned long, 0ul> >(std::__1::tuple<WebCore::NetworkLoadMetrics>&&, WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&))
      55  0x610f70bea void IPC::handleMessage<Messages::WebResourceLoader::DidFinishResourceLoad, WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&)>(IPC::Decoder&, WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&))
      56  0x610f701fc WebKit::WebResourceLoader::didReceiveWebResourceLoaderMessage(IPC::Connection&, IPC::Decoder&)
      57  0x6103c73a9 WebKit::NetworkProcessConnection::didReceiveMessage(IPC::Connection&, IPC::Decoder&)
      58  0x610774e3c IPC::Connection::dispatchMessage(IPC::Decoder&)
      59  0x6107679ad IPC::Connection::dispatchMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)
      60  0x6107759f7 IPC::Connection::dispatchOneIncomingMessage()
      61  0x610793bc8 IPC::Connection::enqueueIncomingMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)::$_14::operator()()
      62  0x610793ad9 WTF::Function<void ()>::CallableWrapper<IPC::Connection::enqueueIncomingMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)::$_14>::call()
      63  0x62609018f WTF::Function<void ()>::operator()() const
      64  0x6260e8f83 WTF::RunLoop::performWork()
      65  0x6260e9934 WTF::RunLoop::performWork(void*)
      66  0x7fff2e435a11 __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION__
      67  0x7fff2e4ef42c __CFRunLoopDoSource0
      68  0x7fff2e418470 __CFRunLoopDoSources0
      69  0x7fff2e4178ed __CFRunLoopRun
      70  0x7fff2e417153 CFRunLoopRunSpecific
      71  0x7fff2d701d96 RunCurrentEventLoopInMode
      72  0x7fff2d701b06 ReceiveNextEventCommon
      73  0x7fff2d701884 _BlockUntilNextEventMatchingListInModeWithFilter
      74  0x7fff2b9b2a73 _DPSNextEvent
      75  0x7fff2c148e34 -[NSApplication(NSEvent) _nextEventMatchingEventMask:untilDate:inMode:dequeue:]
      76  0x7fff2b9a7885 -[NSApplication run]
      77  0x7fff2b976a72 NSApplicationMain
      78  0x7fff56619d77 _xpc_objc_main
      79  0x7fff566189ca xpc_main
      80  0x1091cd077 WebKit::XPCServiceMain()
      81  0x1091cd36b main
      82  0x7fff562bf015 start
      83  0x1
      
      Backtrace for token 5651
      1   0x6179baa97 WebCore::Node::ref()
      2   0x615d77d88 WTF::Ref<WebCore::Document, WTF::DumbPtrTraits<WebCore::Document> >::Ref(WebCore::Document&)
      3   0x615d77d4d WTF::Ref<WebCore::Document, WTF::DumbPtrTraits<WebCore::Document> >::Ref(WebCore::Document&)
      4   0x617396d29 WebCore::toJS(JSC::ExecState*, WebCore::JSDOMGlobalObject*, WebCore::Document&)
      5   0x6173ad378 WebCore::createWrapperInline(JSC::ExecState*, WebCore::JSDOMGlobalObject*, WTF::Ref<WebCore::Node, WTF::DumbPtrTraits<WebCore::Node> >&&)
      6   0x6173ad0a0 WebCore::createWrapper(JSC::ExecState*, WebCore::JSDOMGlobalObject*, WTF::Ref<WebCore::Node, WTF::DumbPtrTraits<WebCore::Node> >&&)
      7   0x615c363de WebCore::toJS(JSC::ExecState*, WebCore::JSDOMGlobalObject*, WebCore::Node&)
      8   0x615c8fbb0 WebCore::toJS(JSC::ExecState*, WebCore::JSDOMGlobalObject*, WebCore::Node*)
      9   0x617384fd3 WebCore::JSDOMWindowBase::updateDocument()
      10  0x6173d677e WebCore::ScriptController::initScriptForWindowProxy(WebCore::JSWindowProxy&)
      11  0x617457455 WebCore::WindowProxy::createJSWindowProxyWithInitializedScript(WebCore::DOMWrapperWorld&)
      12  0x6173c70d6 WebCore::WindowProxy::jsWindowProxy(WebCore::DOMWrapperWorld&)
      13  0x6173d556b WebCore::ScriptController::jsWindowProxy(WebCore::DOMWrapperWorld&)
      14  0x6173d5355 WebCore::ScriptController::evaluateInWorld(WebCore::ScriptSourceCode const&, WebCore::DOMWrapperWorld&, WebCore::ExceptionDetails*)
      15  0x6173d57bd WebCore::ScriptController::evaluate(WebCore::ScriptSourceCode const&, WebCore::ExceptionDetails*)
      16  0x617a04d37 WebCore::ScriptElement::executeClassicScript(WebCore::ScriptSourceCode const&)
      17  0x617a03084 WebCore::ScriptElement::prepareScript(WTF::TextPosition const&, WebCore::ScriptElement::LegacyTypeSupport)
      18  0x617e64798 WebCore::HTMLScriptRunner::runScript(WebCore::ScriptElement&, WTF::TextPosition const&)
      19  0x617e645bf WebCore::HTMLScriptRunner::execute(WTF::Ref<WebCore::ScriptElement, WTF::DumbPtrTraits<WebCore::ScriptElement> >&&, WTF::TextPosition const&)
      20  0x617e455a3 WebCore::HTMLDocumentParser::runScriptsForPausedTreeBuilder()
      21  0x617e45b63 WebCore::HTMLDocumentParser::pumpTokenizerLoop(WebCore::HTMLDocumentParser::SynchronousMode, bool, WebCore::PumpSession&)
      22  0x617e44684 WebCore::HTMLDocumentParser::pumpTokenizer(WebCore::HTMLDocumentParser::SynchronousMode)
      23  0x617e43f8f WebCore::HTMLDocumentParser::pumpTokenizerIfPossible(WebCore::HTMLDocumentParser::SynchronousMode)
      24  0x617e46e9a WebCore::HTMLDocumentParser::append(WTF::RefPtr<WTF::StringImpl, WTF::DumbPtrTraits<WTF::StringImpl> >&&)
      25  0x61785fe62 WebCore::DecodedDataDocumentParser::flush(WebCore::DocumentWriter&)
      26  0x6180c55b4 WebCore::DocumentWriter::end()
      27  0x618084a1f WebCore::DocumentLoader::finishedLoading()
      28  0x6180847bf WebCore::DocumentLoader::notifyFinished(WebCore::CachedResource&)
      29  0x6181c7fdf WebCore::CachedResource::checkNotify()
      30  0x6181ba091 WebCore::CachedResource::finishLoading(WebCore::SharedBuffer*)
      31  0x6181c4ec2 WebCore::CachedRawResource::finishLoading(WebCore::SharedBuffer*)
      32  0x618155a58 WebCore::SubresourceLoader::didFinishLoading(WebCore::NetworkLoadMetrics const&)
      33  0x610f6d50b WebKit::WebResourceLoader::didFinishResourceLoad(WebCore::NetworkLoadMetrics const&)
      34  0x610f71b8a void IPC::callMemberFunctionImpl<WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>, 0ul>(WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>&&, std::__1::integer_sequence<unsigned long, 0ul>)
      35  0x610f71a10 void IPC::callMemberFunction<WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&), std::__1::tuple<WebCore::NetworkLoadMetrics>, std::__1::integer_sequence<unsigned long, 0ul> >(std::__1::tuple<WebCore::NetworkLoadMetrics>&&, WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&))
      36  0x610f70bea void IPC::handleMessage<Messages::WebResourceLoader::DidFinishResourceLoad, WebKit::WebResourceLoader, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&)>(IPC::Decoder&, WebKit::WebResourceLoader*, void (WebKit::WebResourceLoader::*)(WebCore::NetworkLoadMetrics const&))
      37  0x610f701fc WebKit::WebResourceLoader::didReceiveWebResourceLoaderMessage(IPC::Connection&, IPC::Decoder&)
      38  0x6103c73a9 WebKit::NetworkProcessConnection::didReceiveMessage(IPC::Connection&, IPC::Decoder&)
      39  0x610774e3c IPC::Connection::dispatchMessage(IPC::Decoder&)
      40  0x6107679ad IPC::Connection::dispatchMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)
      41  0x6107759f7 IPC::Connection::dispatchOneIncomingMessage()
      42  0x610793bc8 IPC::Connection::enqueueIncomingMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)::$_14::operator()()
      43  0x610793ad9 WTF::Function<void ()>::CallableWrapper<IPC::Connection::enqueueIncomingMessage(std::__1::unique_ptr<IPC::Decoder, std::__1::default_delete<IPC::Decoder> >)::$_14>::call()
      44  0x62609018f WTF::Function<void ()>::operator()() const
      45  0x6260e8f83 WTF::RunLoop::performWork()
      46  0x6260e9934 WTF::RunLoop::performWork(void*)
      47  0x7fff2e435a11 __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION__
      48  0x7fff2e4ef42c __CFRunLoopDoSource0
      49  0x7fff2e418470 __CFRunLoopDoSources0
      50  0x7fff2e4178ed __CFRunLoopRun
      51  0x7fff2e417153 CFRunLoopRunSpecific
      52  0x7fff2d701d96 RunCurrentEventLoopInMode
      53  0x7fff2d701b06 ReceiveNextEventCommon
      54  0x7fff2d701884 _BlockUntilNextEventMatchingListInModeWithFilter
      55  0x7fff2b9b2a73 _DPSNextEvent
      56  0x7fff2c148e34 -[NSApplication(NSEvent) _nextEventMatchingEventMask:untilDate:inMode:dequeue:]
      57  0x7fff2b9a7885 -[NSApplication run]
      58  0x7fff2b976a72 NSApplicationMain
      59  0x7fff56619d77 _xpc_objc_main
      60  0x7fff566189ca xpc_main
      61  0x1091cd077 WebKit::XPCServiceMain()
      62  0x1091cd36b main
      63  0x7fff562bf015 start
      64  0x1