First step to prepare to add just a little bit of typescript (#2047)

* First step to add just a little bit typescript

* First go adding types for scripting

* docs: better cache docs

lib/core/engine/command/cache.js

@@ -2,14 +2,34 @@ import intel from 'intel';
 const log = intel.getLogger('browsertime.command.cache');
 export class Cache {
   constructor(browser, browserName, extensionServer, cdp) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.browserName = browserName;
+    /**
+     * @private
+     */
     this.extensionServer = extensionServer;
+    /**
+     * @private
+     */
     this.cdp = cdp;
   }
 
   /**
-   * Clear the browser cache. Will clear browser cache and cookies.
+   * Clears the browser cache. This includes both cache and cookies.
+   *
+   * For Firefox, it uses the extensionServer setup with specific options.
+   * For Chrome and Edge, it uses the Chrome DevTools Protocol (CDP) commands.
+   * If the browser is not supported, logs an error message.
+   *
+   * @async
+   * @throws Will throw an error if the browser is not supported.
+   * @returns {Promise<void>} A promise that resolves when the cache and cookies are cleared.
    */
   async clear() {
     if (this.browserName === 'firefox') {
@@ -28,7 +48,15 @@ export class Cache {
   }
 
   /**
-   * Clear the browser cache but keep cookies.
+   * Clears the browser cache while keeping the cookies.
+   *
+   * For Firefox, it uses the extensionServer setup with specific options.
+   * For Chrome and Edge, it uses the Chrome DevTools Protocol (CDP) command to clear the cache.
+   * If the browser is not supported, logs an error message.
+   *
+   * @async
+   * @throws Will throw an error if the browser is not supported.
+   * @returns {Promise<void>} A promise that resolves when the cache is cleared but cookies are kept.
    */
   async clearKeepCookies() {
     if (this.browserName === 'firefox') {

lib/core/engine/commands.js

@@ -0,0 +1,115 @@
+import { AddText } from './command/addText.js';
+import { Click } from './command/click.js';
+import { Wait } from './command/wait.js';
+import { Measure } from './command/measure.js';
+import { JavaScript } from './command/javaScript.js';
+import { Switch } from './command/switch.js';
+import { Screenshot } from './command/screenshot.js';
+import { Set } from './command/set.js';
+import { Cache } from './command/cache.js';
+import { Meta } from './command/meta.js';
+import { Watch as StopWatch } from './command/stopWatch.js';
+import { Select } from './command/select.js';
+import { Debug } from './command/debug.js';
+import { AndroidCommand } from './command/android.js';
+import { Android } from '../../android/index.js';
+import { ChromeDevelopmentToolsProtocol } from './command/chromeDevToolsProtocol.js';
+import { ChromeTrace } from './command/chromeTrace.js';
+import {
+  SingleClick,
+  DoubleClick,
+  ClickAndHold,
+  ContextClick,
+  MouseMove
+} from './command/mouse/index.js';
+import { Scroll } from './command/scroll.js';
+import { Navigation } from './command/navigation.js';
+import { GeckoProfiler } from '../../firefox/geckoProfiler.js';
+import { GeckoProfiler as GeckoProfilerCommand } from './command/geckoProfiler.js';
+/**
+ * Represents the set of commands available in a Browsertime script.
+ *
+ */
+export class Commands {
+  constructor(
+    browser,
+    engineDelegate,
+    index,
+    result,
+    storageManager,
+    pageCompleteCheck,
+    extensionServer,
+    context,
+    videos,
+    screenshotManager,
+    scriptsByCategory,
+    asyncScriptsByCategory,
+    postURLScripts,
+    options
+  ) {
+    const measure = new Measure(
+      browser,
+      index,
+      pageCompleteCheck,
+      result,
+      engineDelegate,
+      extensionServer,
+      storageManager,
+      videos,
+      scriptsByCategory,
+      asyncScriptsByCategory,
+      postURLScripts,
+      context,
+      screenshotManager,
+      options
+    );
+
+    const browserProfiler = new GeckoProfiler(browser, storageManager, options);
+    // Profiler
+    this.profiler = new GeckoProfilerCommand(
+      browserProfiler,
+      browser,
+      index,
+      options,
+      result
+    );
+    const cdp = new ChromeDevelopmentToolsProtocol(
+      engineDelegate,
+      options.browser
+    );
+    this.trace = new ChromeTrace(engineDelegate, index, options, result);
+    this.android = new Android(options);
+    this.debug = new Debug(browser, options);
+    this.click = new Click(browser, pageCompleteCheck);
+    this.scroll = new Scroll(browser, options);
+    this.addText = new AddText(browser);
+    this.wait = new Wait(browser, pageCompleteCheck);
+    this.measure = measure;
+    this.navigate = measure._navigate.bind(measure);
+    this.navigation = new Navigation(browser, pageCompleteCheck);
+    this.error = measure._error.bind(measure);
+    this.markAsFailure = measure._failure.bind(measure);
+    this.js = new JavaScript(browser, pageCompleteCheck);
+    this.switch = new Switch(
+      browser,
+      pageCompleteCheck,
+      measure._navigate.bind(measure)
+    );
+    this.set = new Set(browser);
+    this.stopWatch = new StopWatch(measure);
+    this.cache = new Cache(browser, options.browser, extensionServer, cdp);
+    this.meta = new Meta();
+    this.screenshot = new Screenshot(screenshotManager, browser, index);
+    this.cdp = cdp;
+    this.android = new AndroidCommand(options);
+    this.debug = new Debug(browser, options);
+    this.mouse = {
+      moveTo: new MouseMove(browser),
+      contextClick: new ContextClick(browser),
+      singleClick: new SingleClick(browser, pageCompleteCheck),
+      doubleClick: new DoubleClick(browser, pageCompleteCheck),
+      clickAndHold: new ClickAndHold(browser)
+    };
+    this.select = new Select(browser);
+  }
+}

lib/core/engine/context.js

@@ -0,0 +1,65 @@
+/**
+ * Class representing the context of a Browsertime run.
+ *
+ * @class
+ */
+export class Context {
+  /**
+   * Creates an instance of Context.
+   *
+   * @param {Object} options - Configuration options for the Browsertime run.
+   * @param {Object} result - Object to store the results of the Browsertime run.
+   * @param {intel.Logger} log - Logger for recording events or errors.
+   * @param {import('../../support/storageManager.js').StorageManager} storageManager - Manages storage for the Browsertime run.
+   * @param {number} index - Index representing the current iteration or run.
+   * @param {import('selenium-webdriver').WebDriver} webdriver - WebDriver instance from Selenium for browser automation.
+   * @param {import('selenium-webdriver').WebDriver} instantiatedDriver - WebDriver instance returned by Selenium's `builder.build()`.
+   */
+  constructor(
+    options,
+    result,
+    log,
+    storageManager,
+    index,
+    webdriver,
+    instantiatedDriver
+  ) {
+    /**
+     * @type {Object}
+     */
+    this.options = options;
+
+    /**
+     * @type {Object}
+     */
+    this.result = result;
+
+    /**
+     * @type {intel.Logger}
+     */
+    this.log = log;
+
+    /**
+     * @type {number}
+     */
+    this.index = index;
+
+    /**
+     * @type {import('../../support/storageManager.js').StorageManager}
+     */
+    this.storageManager = storageManager;
+
+    /**
+     * @type {Object}
+     */
+    this.taskData = {};
+
+    /**
+     * @type {{webdriver: import('selenium-webdriver').WebDriver, driver: import('selenium-webdriver').WebDriver}}
+     */
+    this.selenium = {
+      webdriver,
+      driver: instantiatedDriver
+    };
+  }
+}