Web-page Javascript code-coverage

Getting code-coverage of browser-Javascript files requires interaction with an external tool that does JS-code instrumentation. The most common approach requires that Javascript files be instrumented manually, then upload onto the web-server for the web-page-under-test (WUT). This latter install is a manual step and may be considered intrusive. There are other approaches and various tools for Javascript instrumentation.

About JscovTestUtil

JscovTestUtil came about due to the author’s requirement to test a MCU (micro-computer-unit) that supported WiFi and enough storage to run a small web-server (an ESP8266 device). Manual instrumenting and upload, to the MCU, approach would be time consuming and subject to coordination error, while placing wear-&-tear on the MCU development board.

JSCover was found to meet the requirements needed for automatic instrumentation and no re-upload to the device. So the design and development of JscovTestUtil was instigated.

Using JSCover's proxy-server of on-the-fly instrumentation (which works great), and interacting with Selenium and TestNG, the goal of a seamless flow-through for getting code-coverage of JS-files on a MCU device/web-server works.

Capabilities/features

JSCover Javascript handling

JscovTestUtil employs JSCover's proxy-server capability to do on-the-fly instrumentation of JS-files.

For all intent-&-purposes, users of JscovTestUtil will find it removes 'manual instrumentation' for the user and subsequent upload to web-servers. The removal of any upload reduces the risk of leaving instrumented JS-files on the web-server by accident.

The proxy-server approach (simplified) allows processing in the following manner:

• browser/user: Browser requests web-page.
• proxy-server: Pass through requests to web-server un-filtered.
• web-server: Respond(s) with file(s) for GET request.
• proxy-server: Intercept returned GET responses:
  • Pass-through all none Javascript files.
  • Instrument Javascript files as per JSCover processing and then upload to browser.
  • Store original Javascript files for JSCover's reporting system.

JscovTestUtil approach

For JscovTestUtil to work setup/configuration of Selenium V3 and JSCover is needed.

How-to setup/configure is outside this documents scope, and it is assumed users will follow-up with Selenium and/or JSCover documentation.

IDEA: consider using WebDriverManager for Selenium setup/install/configuration management.

The following diagram and its ordered steps is a brief on how JscovTestUtil interacts with hi-level "components" to do Javascript code-coverage in a test Selenium (Java) and @Test framework environment.

Note: JscovTestUnit causes JSCover to generate report-files, however, creation of files is NOT concurrent friendly for parallel processing of @Test testcase-scripts.

JscovTestUnit is a part of the Test environment as a Selenium add-in. It is a library that provides JSCover control interaction methods to simplify/integrate run-time configuration.

1. Test setup:
   • Start the proxy-server via ProcessBuilder using the JSCover executable directory.
2. Testing:
   • Begin executing tests, perform GET-URL action.
     • Proxy-server: passes GET requests directly to web-server.
3. Web-server:
   • Respond to GET requests and sends files back to requestor (for files: HTML, CSS, JS,...).
   1. Proxy-server: Javascript file(s) are intercepted by JSCover proxy-server and instrumented, if not excluded from instrumentation.
   2. Proxy-server: Instrumented files are forwarded to browser.
   3. Proxy-server: Excluded from instrumentation files are passed-through to the browser.
   4. Proxy-server: Records the original Javascript and retains them in the JSCover reports directory.
4. Testing:
   • Performs normal test actions via the WebDriver API.
5. Testing/capture report:
   • invoke a store-report at end of each test, or during testing, or whenever.
   1. Instrumented Javascript: Invoke the jscoverage_report(...) function in the instrumented Javascript. This will cause the script to forward captured results to the proxy-server directly.
   2. Proxy-server: Receives jscoverage JSON and other datum which will be formatted and converted into JSCover report format files.
   3. Proxy-server: Report-files are stored in the JSCover reports directory. JSCover will also merge the data if existing datum files present.
6. Testing/stop:
   • On testing stop a request to terminate and stop the proxy-server is "called". This will cause a store-report first before stopping the JSCover proxy-server process on the system.

JscovTestUtil has been designed to be integral with IDE's and/or using external locations for resources, the resources being Selenium V3 WebDriver executables and the JSCover program.

Selenium setup is involved, in that WebDriver executables are OS-platform and browser type dependent, JSCover setup has no dependencies as such.

Notes: An assumption is made that users are familiar with Selenium V3's WebDriver setup/configuration.

Also, the user is capable of configuring JSCover as per its setup/configuration arrangements.

Considerations

It is recommended that JSCover and Selenium WebDrivers be installed on a machines local-file-system, thus supporting distributed development and no reliance on a network connection.

IDE integration

IDE JscovTestUtil

The integral support of JscovTestUtil is focused on IDE use, where all the resources are contained within an IDE's project structure. This is done by making JSCover part of the test-environment.

null caption

JSCover IDE integration "installing" JSCover within the IDE's "user.dir" structure at '<user.dir>/jscoverInst' directory. Notes The reports directory is introduced by JscovTestUtil as a single location in the JSCover directory to be the "goto" directory for viewing. Additionally, strongly consider making 'reports' ignored in an '.ignore' file if source controlled. Consider removing some directories from JSCover (such as "examples") to reduce the amount of storage used.	Selenium Web-driver install Selenium V3 WebDrivers are independently provided files for each browser type. There is a specific manner in which they are setup/install to interface with Selenium Java. The user should refer to Selenium V3 documentation on how this is done. Also, consider using WebDriverManager class for automatic management for WebDriver's in your test environment. (WebDriverManager is an Apache 2.0 licensed artifact.)
/<user.dir> +- /jscoverInst +- /.... +- /.... +- /reports : : +--- .... +--- .... +--- .... 75% 100%
Structure allows cross-platform of project distribution so shopping around is unnecessary. CON: Large amount of storage on SCM system PRO: all users have the same JSCover programs PRO: single person program update into a repository PRO: SCM pull provides the driver distribution, vs individual download PRO: supports distributed SCM development when network is not available PRO: structure can be reduced in size by removing 'items' e.g. Examples

External JSCover and/or WebDriver resources

Using the external resources capability of JscovTestUtil allows users to choose how-to and where-from resources are accessed. The following diagram outlines access arrangements. It is the users decision to use the external resources arrangement:

• JSCover can be identified as an external directory for processing the JSCover needs of JscovTestUtil.

75% 100%

Test scripts

      <script type="text/javascript" src="./subdir/file1.js"></script>
      <script type="text/javascript" src="./subdir/fileA1.js"></script>
      <script type="text/javascript" src="./file2.js"></script>
      <script type="text/javascript" src="/file3.js"></script>

     WebDriver driver = new FirefoxDriver();

     // the normal manner of API actions
     driver.get("http://........);
     WebElement myTestElement = driver.findElement(........);
        ::

     JscovTestUtil jscovObj = new JscovTestUtil(3129, "base");

     jscovObj.setOnCodeCoverage();
     jscovObj.startProxyServer();

     WebDriver jscovDriver 
         = jscovObj.webDriverForJSCoverProxy(JscovBrowserKind.FIREFOX);

     // the normal manner of API actions
     jscovDriver.get("http://........);
     WebElement myTestElement = jscovDriver.findElement(........);
        ::

package package-name;

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.testng.annotations.AfterClass;
import org.testng.annotations.AfterSuite;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.BeforeSuite;
import org.jtestdb.selenium.jscov.JscovTestUtil;
import static org.jtestdb.selenium.jscov.JscovBrowserKind.*;

import WebDriverManager......??? users choice

/**
 * Class that is a template to show use of before-suite and 
 * after-suite use and interaction with JscovTestUtil.
 * 
 * Free to use template.
 */
public class JscoverExtendableTestClass {
  // variable for the JscovTestUtil object
  // and a WebDriver variable to allow after-suite to clean-up on finish
  protected static JscovTestUtil jscovObject;
  protected static WebDriver driver;

  // - - - - - - SUITE - - - - - - - 
  //
  @BeforeSuite
  public void suiteBefore() {

    // prepare the Selenium drivers (as per user's test environment)
    //
    // WebDriverManager is an Apache 2.0 licensed Java library that allows
    // automatic install/update of Selenium V3 WebDrivers and setup. 
    //
    WebDriverManager.chromedriver().setup();
    WebDriverManager.firefoxdriver().setup();

    // prepare for code-coverage
    jscovObject = new JscovTestUtil(3129, "base");

    if (true) {    ?? need to code this appropriately
      jscovObject.setOnCodeCoverage();
    } else {
      jscovObject.setOffCodeCoverage();
    }
    jscovObject.setOnViewReport();
    jscovObject.reportIntoTimeStampDir(3);
    //
    jscovObject.startProxyServer();
  }

  @AfterSuite
  public void suiteAfter() {
    jscovObject.stopProxyServer(30);
    jscovObject.viewReportDo(8080);
  }

  // - - - - - - CLASS - - - - - - - 
  //
  @BeforeClass
  public void classBefore() {
    driver = jscovObject.webDriverForJSCoverProxy(FIREFOX);
  }

  @AfterClass
  public void classAfter() {
    jscovObject.storeJscoverReport(30);
        
    if (driver != null) {
      // knock the driver down
      // driver.close() the test item remains alive for some
      // reason; so do quit
      driver.quit();
      driver = null;
    }
  }
}         
                

Copyright (c) 2019 dbradley.