Add evalVMScript public API

domenic · domenic · commit 24c28fdb575f · 2016-07-02T16:02:25.000-04:00
Closes #1543.
diff --git a/README.md b/README.md
@@ -548,6 +548,15 @@ At present jsdom does not handle navigation (such as setting `window.location.hr
 jsdom.changeURL(window, "https://example.com/");
 ```
 
+#### Running vm scripts
+
+Although in most cases it's simplest to just insert a `<script>` element or call `window.eval`, in some cases you want access to the raw [vm context](https://nodejs.org/api/vm.html) underlying jsdom to run scripts. You can do that like so:
+
+```js
+const script = new vm.Script("globalVariable = 5;", { filename: "test.js" });
+jsdom.evalVMScript(window, script);
+```
+
 ## What Standards Does jsdom Support, Exactly?
 
 Our mission is to get something very close to a headless browser, with emphasis more on the DOM/HTML side of things than the CSS side. As such, our primary goals are supporting [The DOM Standard](http://dom.spec.whatwg.org/) and [The HTML Standard](http://www.whatwg.org/specs/web-apps/current-work/multipage/). We only support some subset of these so far; in particular we have the subset covered by the outdated DOM 2 spec family down pretty well. We're slowly including more and more from the modern DOM and HTML specs, including some `Node` APIs, `querySelector(All)`, attribute semantics, the history and URL APIs, and the HTML parsing algorithm.
diff --git a/lib/jsdom.js b/lib/jsdom.js
@@ -285,6 +285,10 @@ exports.blobToBuffer = function (blob) {
   return blob && blob[blobSymbols.buffer];
 };
 
+exports.evalVMScript = (window, script) => {
+  return script.runInContext(idlUtils.implForWrapper(window._document)._global);
+};
+
 function processHTML(config) {
   const window = exports.jsdom(config.html, config).defaultView;
   const implImpl = idlUtils.implForWrapper(window.document.implementation);
diff --git a/test/jsdom/misc.js b/test/jsdom/misc.js
@@ -13,6 +13,7 @@ const https = require("https");
 const EventEmitter = require("events").EventEmitter;
 const zlib = require("zlib");
 const parseURL = require("url").parse;
+const vm = require("vm");
 
 function tmpWindow() {
   return jsdom.jsdom().defaultView;
@@ -856,6 +857,15 @@ describe("jsdom/miscellaneous", () => {
 
   // these tests require file system access or they start a http server
   describe("node specific tests", { skipIfBrowser: true }, () => {
+    specify("evalVMScript", () => {
+      const window = jsdom.jsdom().defaultView;
+      const script = new vm.Script(`globalVariable = "value";`);
+
+      jsdom.evalVMScript(window, script);
+
+      assert.strictEqual(window.globalVariable, "value");
+    });
+
     specify("fix_for_issue_172", () => {
       jsdom.env(`<html><body><script type="text/javascript"></script></body></html>`, [
         "file:" + path.resolve(__dirname, "../jquery-fixtures/jquery-1.6.2.js")
