test: add heap snapshot tests

Add a number of tests that validate that heap snapshots
contain what we expect them to contain, and cross-check
against a JS version of our own embedder graphs.

PR-URL: https://github.com/nodejs/node/pull/21741
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/test/common/README.md b/test/common/README.md
index 111ce45b00..c0051ad9f7 100644
--- a/test/common/README.md
+++ b/test/common/README.md
@@ -10,6 +10,7 @@ This directory contains modules used to test the Node.js implementation.
 * [DNS module](#dns-module)
 * [Duplex pair helper](#duplex-pair-helper)
 * [Fixtures module](#fixtures-module)
+* [Heap dump checker module](#heap-dump-checker-module)
 * [HTTP2 module](#http2-module)
 * [Internet module](#internet-module)
 * [tmpdir module](#tmpdir-module)
@@ -538,6 +539,42 @@ Returns the result of
 Returns the result of
 `fs.readFileSync(path.join(fixtures.fixturesDir, 'keys', arg), 'enc')`.
 
+## Heap dump checker module
+
+This provides utilities for checking the validity of heap dumps.
+This requires the usage of `--expose-internals`.
+
+### heap.recordState()
+
+Create a heap dump and an embedder graph copy for inspection.
+The returned object has a `validateSnapshotNodes` function similar to the
+one listed below. (`heap.validateSnapshotNodes(...)` is a shortcut for
+`heap.recordState().validateSnapshotNodes(...)`.)
+
+### heap.validateSnapshotNodes(name, expected, options)
+
+* `name` [<string>] Look for this string as the name of heap dump nodes.
+* `expected` [<Array>] A list of objects, possibly with an `children`
+  property that points to expected other adjacent nodes.
+* `options` [<Array>]
+  * `loose` [<boolean>] Do not expect an exact listing of occurrences
+    of nodes with name `name` in `expected`.
+
+Create a heap dump and an embedder graph copy and validate occurrences.
+
+<!-- eslint-disable no-undef, no-unused-vars, node-core/required-modules, strict -->
+```js
+validateSnapshotNodes('TLSWRAP', [
+  {
+    children: [
+      { name: 'enc_out' },
+      { name: 'enc_in' },
+      { name: 'TLSWrap' }
+    ]
+  }
+]);
+```
+
 ## HTTP/2 Module
 
 The http2.js module provides a handful of utilities for creating mock HTTP/2