Skip to content

WTI‐UI Code Debugging

Jump to bottom
John Clevenger edited this page Jan 13, 2025 · 8 revisions

Overview

As described at Web Access and Web Team Interface Implementation, the PC² WTI-UI project implements a client (browser)-side component which communicates with the WTI Server (which in turn communicates with the PC² server). The browser client-side code is implemented as an Angular project; as of PC² Version 9.9, the WTI-UI project is based on Angular V16. (See WTI UI Angular Project Structure and WTI UI Project Implementation Details for information on the organization of the WTI-UI project.)

The WTI-UI Angular modules are written in TypeScript, which is a superset of JavaScript. One of the steps of building a PC² distribution involves building the WTI-UI project, which in turn involves converting the Angular Typescript code into JavaScript code which can be executed by a browser -- a process called transpilation. The building of the WTI-UI project -- and hence the transpilation process -- occurs automatically as part of overall PC² distribution building process (see Development Environment and Building a PC2 Distribution for details).

JavaScript vs. TypeScript

Browsers execute code which is written in JavaScript. By default, the WTI-UI transpilation process converts the Angular TypeScript code into JavaScript code which has been both "minified" and "uglified" ("minification" is the process of removing extraneous information, such as whitespace and redundant delimiters, while "uglification" refers to a process for "obfuscating" code by making it harder -- though not impossible -- to read). It is this "minified" and "uglified" code which is downloaded and executed by a browser when a team points the browser at the PC² "login" URL.

All modern browsers support built-in debuggers which allow a developer, through use of the browser console, to do things like set breakpoints and "step through" the code being executed by the browser. Unfortunately, stepping through uglified JavaScript code is a virtually impossible task; the "uglification" makes it extremely hard to understand what is happening in the code.

Source Maps

What are source maps?

A "source map" a file which explains (to the browser) the mapping between the actual JavaScript code being executed and the corresponding TypeScript code from which that JavaScript code was created via the transpilation process. Once the browser is configured to understand the "source map", its debugger can display the original TypeScript code, including allowing things like setting breakpoints in the TypeScript code that automatically break at the corresponding (actual) JavaScript code executing in the browser.

Creating Source Maps

The overall process of building the WTI-UI Angular application is controlled by the contents of a file named angular.json, which resides in the root WTI-UI project folder. Source maps are not automatically created when the WTI-UI project is built (nor should they be; automatic generation of source mpas would potentially provide security holes because it would allow a contest team to very easily observe what happening in the browser as the WTI-UI code executes). To instruct the PC² build process to generate source maps for the Angular code, the architect>build>options section of the angular.json file must be modified, as follows:

      ...
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist/WTI-UI",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "src/tsconfig.app.json",
            "assets": [
              "src/favicon.ico",
              "src/assets"
            ],
            "styles": [
              "src/styles/styles.scss"
            ],
            "scripts": [],              <== Note added trailing comma
            "sourceMap": true,          <== These two lines must be added
            "optimization": false       <== in order to generate source maps
          },
      ...

Additional Notes:

  • Developers should never "push" their updated angular.json file. Doing so would result in public distributions of PC² containing source maps, which represent a potential security issue. The updated angular.json file which causes generation of source maps should be used only in the developer's local environment.
  • The process which actually builds the WTI-UI project is actually invoked from the build.xml file in the WTI-API project (that is, the WTI-UI project is never built by itself, but rather only built as part of building the overall WTI system, which is driven by the WTI-API build.xml file). The WTI-UI build (invoked from the ngbuild target in the WTI-API build.xml) builds source maps (if enabled as described above) and stores them in the dist folder under the WTI-UI project. However, when the WTI-UI build finishes, the WTI-API build.xml target named collect then immediately moves the resulting map files from the WTI-UI dist folder to the WTI-API build>WebContent>WTI-UI folder.
  • A good test to verify that your system is generating source maps is to run the WTI-API build process (by executing WTI-API>buildWTI.xml, WTI-API>package.xml, or pc2v9>package.xml). The result of any of these commands should be to produce several .map files in WTI-API>WebContent>WTI-UI.

Using Source Maps in Chrome

In order to use WTI-UI source maps (to do things like set breakpoints in TypeScript source, step into or over TypeScript method calls, etc.) the browser must be made aware of the source maps. The following describes one successful set of steps to get this working in Chrome (version 131.0.6778.109 was used). Other browsers should have similar (although not necessarily identical) steps.

  1. Verify that your WTI distribution contains source maps (see above).
  2. Enable Source Maps in Chrome DevTools:
  • Open Chrome DevTools (Right-click on the page then select "Inspect").
  • Go to Settings (Gear icon in the top right corner).
  • In the Sources section, enable (check) the following options:
    • Enable JavaScript source maps
    • Enable CSS source maps
  1. Access WTI-UI Source Maps in DevTools:
  • Start a PC² server.
  • Start a WTI-API server.
  • Enter the WTI URL in a browser (e.g. "http://localhost:8080")
  • Navigate to the Sources panel in DevTools.

You should see the original TypeScript files (rather than the compiled/obfuscated JavaScript files) under "sources". You can set breakpoints and debug your Angular code directly in these files.

To set a breakpoint at the very start of the WTI-UI Angular code, select the "main.ts" source file and set a breakpoint on the line

platformBrowserDynamic().bootstrapModule(AppModule)

Then refresh/reload the page.

Note: the current build of PC² includes a variable named DEBUG_MODE, defined in file constants.ts in the WTI-UI project as having the value 'true'. There are numerous places in the Angular code which currently produce console output when DEBUG_MODE is true. To disable this output, change the value of DEBUG_MODE to 'false' and rebuild the PC² project.

See Also

PC2 Logo

Clone this wiki locally