Set up an environment to create UI automation tests for Oracle JET web apps

Introduction

This tutorial shows you how to set up an Oracle JET web app’s environment so that, in the next tutorial, you can write and run tests to perform automated UI testing of the Oracle JET web app that you created in earlier tutorials.

You’ll use a number of UI automation test libraries to create the tests that you execute. One of these libraries is Oracle JET Component WebElements (@oracle/oraclejet-webdriver), a UI automation library built on top of Selenium WebDriver, and designed to work with Oracle JET components.

Selenium WebDriver requires you to write and run test scripts in an app that uses commonJS as a module type. Oracle JET web apps use amd as a module type. For this reason, we write our Selenium WebDriver tests in a separate app that we execute against the Oracle JET web app.

Another requirement is that the version of the oraclejet-webdriver NPM package, in the CommonJS-based app that contains your tests, must match the version of the Oracle JET web app that you run the tests against. Verify that the version of your Oracle JET web app’s @oracle/oraclejet package matches the version of the CommonJS-based web app’s @oracle/oraclejet-webdriver package. That is, if the Oracle JET web app uses @oracle/oraclejet@15.1.2, the entry in the CommonJS-based app must be @oracle/oraclejet-webdriver@15.1.2.

If there is a mismatch between these two versions, you’ll encounter an error message like the following where an attempt was made to execute tests written using @oracle/oraclejet-webdriver@15.1.2 against an Oracle JET 16.0.0 web app.

Error: version mismatch: oraclejet {"revision":"2024-01-13_12-50-29","version":"15.1.5"}, 
                         oraclejet-webdriver {"version": "16.0.0", "revision": "2024-01-22_18-30-09"}
     at checkVersions (node_modules\@oracle\index.ts:187:11)
     at processTicksAndRejections (node:internal/process/task_queues:95:5)
     at async Object.get (node_modules\@oracle\index.ts:217:7)

To determine the version of the NPM packages in your CommonJS-based app and the Oracle JET web app that you want to test, run the following command in a terminal window from the root directory of each app’s source project.

npm list --depth=0

The terminal window displays the NPM packages and version numbers that each app uses. The version returned for the @oracle/oraclejet package when you run the command in your Oracle JET web app must match the version of the @oracle/oraclejet-webdriver package when you run the command in the CommonJS-based app’s root directory. That is, if the Oracle JET web app uses @oracle/oraclejet@15.1.5, the entry in the CommonJS-based app must be @oracle/oraclejet-webdriver@15.1.5.

Objectives

In this tutorial, you will learn how to create a CommonJS-based web app to host and run Selenium WebDriver–based tests. You will also write and run tests for two Input Text components in an Oracle JET web app that you create to validate that you have correctly created and configured the CommonJS-based web app that contains your tests.

Prerequisites

Task 1: Create a CommonJS-based App to Write Tests

You’ll create an Oracle JET app using a webdriver-ts template that is configured with the NPM packages and features needed to create and execute Selenium WebDriver tests. This app will, for example, have a module type of commonJS, which is required by Selenium WebDriver.

  1. In your file system, in the location where you want the CommonJS-based app to reside, open a terminal window and create the app.

    npx @oracle/ojet-cli create JET-WebDriver-Tests --template=webdriver-ts

    The Oracle JET tooling creates the app in the JET-WebDriver-Tests directory and displays progress messages until it finishes.

  2. In the ./JET-WebDriver-Tests/src/__tests__ directory, create a file named ValidateSetup.spec.ts.

  3. Copy and paste the code from the attached file into your newly-created JET-WebDriver-Tests/src/__tests__/ValidateSetup.spec.ts file, and then save and close the file.

Task 2: Create an Oracle JET Web App

You’ll create an Oracle JET web app to display two Input Text components. On completion of this task, we can execute the ValidateSetup.spec.ts test script that we created in the JET-WebDriver-Tests app in the previous task.

  1. In your file system, in the location where you want the Oracle JET web app to reside, open a terminal window and create the app.

    npx @oracle/ojet-cli create JET-Basic-App --template=navdrawer --typescript

    The Oracle JET tooling creates the app in the JET-Basic-App directory and displays progress messages until it finishes.

  2. In a terminal window, change to the JET-Basic-App directory and install the following NPM packages so that tests can be executed against the Oracle JET web app.

    npm i -D chai@4.3.10

    Note: We install version 4.3.10 of Chai as the version must match the one that we use in our CommonJS-based app (JET-WebDriver-Tests). Version 5.x and later of Chai cannot be used in the commonJS-based projects where we write Selenium WebDriver test scripts.

  3. In the ./JET-Basic-App/src/js/path_mapping.json file, verify that it includes an entry for Chai, as in the following example that was added to the end of the file. If there is no such entry, add one.

    . . .
      "cdnPath": "ojcss"
      }
   },
   "chai": {
      "cwd": "node_modules/chai/",
      "debug": {
      "src": "chai.js",
      "path": "libs/chai/chai.js"
     },
      "release": {
      "src": "chai.js",
      "path": "libs/chai/chai.js"
      }
    }
  }
}

  4. Open the ./JET-Basic-App/src/ts/views/dashboard.html file and replace its content with the content from the attached file.

  5. Open the ./JET-Basic-App/src/ts/viewModels/dashboard.ts file and replace its content with the content from the attached file.

  6. In the terminal window, change to the JET-Basic-App directory and run the app.

    npx ojet serve

    The Oracle JET tooling runs the web app in a local web browser.

Task 3: Run the WebDriver Test

  1. In a new terminal window, change to the JET-WebDriver-Tests directory and run the test to confirm that you have set up the test creation environment correctly.

    npm test ./src/__tests__/ValidateSetup.spec.ts

  2. Wait for the test to complete.

    An instance of the Chrome browser opens temporarily, the values displayed by the Input Text components change, and the Chrome browser instance then closes. On successful completion, the terminal window displays output similar to the following.

    oracle-PC-NAME MINGW64 /c/JET-WebDriver-Tests
$ npm test ./src/__tests__/ValidateSetup.spec.ts
   
> JET-WebDriver-Tests@1.0.0 test
> node node_modules/mocha/bin/mocha --require ts-node/register --timeout=0 ./src/__tests__/ValidateSetup.spec.ts
   
Confirm Test Creation Environment is Set Up Correctly
   
DevTools listening on ws://127.0.0.1:65293/devtools/browser/f1cd733a-6a46-4442-9bc9-d3b012784548
✔ Set a value into oj-input-text and use Chai's expect assertion to confirm value change (733ms)
✔ Set a new value for the Knockout observable in the viewModel and use Expectation 
from @oracle/oraclejet-webdriver to confirm change (832ms)
   
2 passing (1m)
   
oracle-PC-NAME MINGW64 /c/JET-WebDriver-Tests
$

Note: If you review the content of the ValidateSetup.spec.ts file and the console output after running the test, you’ll notice that the second test uses assertViewModelValue to test the value of viewModel code. This type of test can only be used if the Oracle JET app that you test uses the MVVM architecture. Oracle JET apps that use the virtual DOM architecture cannot be tested using the assertViewModelValue function.

Next Step

To proceed to the next tutorial in this learning path, click here.

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.