From 83fd5fd05d26078e2fe544bd462dca414e435696 Mon Sep 17 00:00:00 2001
From: John Hildenbiddle <john@hildenbiddle.com>
Date: Tue, 7 Jul 2020 20:22:52 -0500
Subject: [PATCH] Update options and add JSDoc comments

---
 tests/helpers/docsifyInit.js | 54 +++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/tests/helpers/docsifyInit.js b/tests/helpers/docsifyInit.js
index 68d24e24..8299b3b1 100644
--- a/tests/helpers/docsifyInit.js
+++ b/tests/helpers/docsifyInit.js
@@ -1,6 +1,25 @@
 const stripIndent = require('common-tags/lib/stripIndent');
 const { serverIP, serverPort } = require('./server.js');
 
+/**
+ * Playwright helper for dynamically creating custom docsify sites.
+ *
+ * @param {Object} page Playwright page reference
+ * @param {Object} options options object
+ * @param {Object} [options.config] docsify configuration (merged with default)
+ * @param {String} [options.content] homepage markdown
+ * @param {String} [options.coverpage] coverpage markdown
+ * @param {String} [options.navbar] navbar markdown
+ * @param {String} [options.sidebar] sidebar markdown
+ * @param {Array[]|Array[][]} [options.routes] custom routes as [path, response] (See https://playwright.dev/#path=docs%2Fapi.md&q=routefulfillresponse for details)
+ * @param {String} [options.style] CSS to inject via <style> tag
+ * @param {string|String[]} [options.styleURLs=['/lib/themes/vue.css']] External CSS to inject via <link rel="stylesheet"> tag(s)
+ * @param {String} [options.script] JS to inject via <script> tag
+ * @param {string|String[]} [options.scriptURLs] External JS to inject via <script src="..."> tag(s)
+ * @param {String} [options.url=`http://${serverIP}:${serverPort}`] URL of local test server
+ * @param {String} [options.docsifyURL='/lib/docsify.js']
+ * @param {String} [options.waitForSelector='#main']
+ */
 async function docsifyInit(page, options) {
   const defaults = {
     config: {},
@@ -22,7 +41,7 @@ async function docsifyInit(page, options) {
     ...options,
   };
 
-  // Routes - General
+  // Routes
   if (settings.routes.length > 0 && typeof settings.routes[0] === 'string') {
     settings.routes = [settings.routes];
   }
@@ -37,7 +56,7 @@ async function docsifyInit(page, options) {
     }
   });
 
-  // Routes - Docsify Markdown
+  // Docsify markdown
   [
     [settings.content, '**/README.md'],
     [settings.coverpage, '**/_coverpage.md', { coverpage: true }],
@@ -57,8 +76,9 @@ async function docsifyInit(page, options) {
     }
   });
 
-  // Load URL
+  // Load URL and wait for 'load' event
   await page.goto(settings.url);
+  await page.waitForLoadState();
 
   // Docsify configuration
   if (Object.keys(settings.config).length > 0) {
@@ -67,19 +87,39 @@ async function docsifyInit(page, options) {
     }, settings.config);
   }
 
-  // CSS
-  settings.styleURLs.forEach(async url => await page.addStyleTag({ url }));
+  // CSS (must resolve all before proceeding)
+  await Promise.all(settings.styleURLs.map(url => page.addStyleTag({ url })));
+  if (settings.style) {
+    await page.evaluate(data => {
+      const headElm = document.querySelector('head');
+      const styleElm = document.createElement('style');
 
-  // JavaScript (must load/resolve sequentially)
+      styleElm.textContent = data;
+      headElm.appendChild(styleElm);
+    }, stripIndent`${settings.style}`);
+  }
+
+  // JavaScript (must load/resolve sequentially to guaraantee execution order)
   settings.scriptURLs.push(settings.docsifyURL);
   for (const url of settings.scriptURLs) {
     await page.addScriptTag({ url });
   }
+  if (settings.script) {
+    await page.evaluate(data => {
+      const headElm = document.querySelector('head');
+      const scriptElm = document.createElement('script');
 
-  // Detect docsify "complete" by waiting for specified element
+      scriptElm.textContent = data;
+      headElm.appendChild(scriptElm);
+    }, stripIndent`${settings.script}`);
+  }
+
+  // Docsify "Ready"
   if (settings.waitForSelector) {
     await page.waitForSelector(settings.waitForSelector);
   }
+
+  return Promise.resolve();
 }
 
 module.exports = docsifyInit;