6 Test and Debug Applications

As your work on your application, it's important to test and debug it to ensure a smooth end-to-end experience for your users.

Because Visual Builder applications are essentially client-side HTML applications written in JavaScript, you can use your browser's development tools for debugging. For example, when you run your Visual Builder application in Chrome, you can use the Developer tools option to view network traffic between the client's browser and your REST sources of data in the Network tab.

You can also track error messages and notifications from your application in the Console tab. Visual Builder applications run on verbose output mode, which gives you the complete picture of what's going on in your app.

Audit Application Code

Use the Audits feature to check and verify the code of your application as you develop it.

When you use Audits, Visual Builder scans and runs checks on the code in your application and displays errors and warnings, if any. In addition to reporting errors related to JET components, the Audits pane displays other errors, such as syntax errors, warnings for missing dependencies, and translation-related errors. You can view details for the issues and also resolve issues from the Audits Pane.

  1. Click Audits to view the Audits pane.
    The application is scanned and results are displayed in the Audits pane. The results are sorted into four categories based on severity.
  2. Review the listed issues.
    For each issue, you can review severity, issue details, source and location.
  3. Optionally, filter the issue list to review specific issues by using the Search field and by selecting or deselecting the severity buttons.
  4. Select an issue and click the Menu icon (Menu icon).
  5. Select Open in Source Editor or Open Artifact to view the source code for the issue.
  6. Select Do not report this type of defect again to ignore similar defects in future.
  7. Resolve the issue, if possible, by selecting the appropriate option.

    For example, for the String not externalized for translation issue, select the Add to translation bundle option to fix the issue.
    Description of audits_extr_tran_resolve-png.png follows
    Description of the illustration audits_extr_tran_resolve-png.png

    In the image, notice that the entry for the artifact in the Navigator and other entries in the Designer highlight the presence of an audit error (syntax error in the main-start file) through the use of red underline and red dots.

The Audits feature in the Designer includes the built-in rules from the Oracle JET Audit Framework (JAF) by referencing the rule pack and the JAF utility (ojaf) that is hosted on the Content Delivery Network (CDN) for Oracle JET at https://static.oracle.com/cdn/jet/. Every Oracle JET release includes the JAF utility and JAF metadata, plus the JAF metadata for previous releases of JET. You can configure built-in JAF rules in the Source editor of the Audits feature. Custom JAF configurations that deal with the file system, custom rule plugins, and so on will not be evaluated because JAF does not execute on the Visual Builder backend. JAF runs on the client. The following example demonstrates how to reference JAF from the CDN and enable a built-in rule that is disabled by default. For more information about JAF, including the built-in rules that it includes, see About Auditing Oracle JET Applications in Developing Applications with Oracle JET.

{
    "paths": {
        "exclude": [
            "build/**",
            "docs/**",
            "scripts/**",
            "tests/**",
            "**/private",
            "+(web|mobile)Apps/**/resources/components/**/lib/*"
        ]
    },
    "rules": {},
    "auditors": {
        "jaf": {
            "cdnPath": "https://static.oracle.com/cdn/jet/",
            "version": "9.0.0",
             "jafOptions": {
                "ruleMods": {
                    "JET": {
                        "oj-css-style-override": {
                            "enabled": true
                        }
                    }
                }
            }
        }
    }
}

Preview an App in Debug Mode

When testing your application, you typically preview it to see it the way your user would. Sometimes though, you might want to preview the application in debug mode to troubleshoot issues with the Visual Builder runtime and Oracle JET libraries—runtime dependencies that make sure your app works as intended.

The Preview option in the header facilitates both modes:
Description of preview.png follows
Description of the illustration preview.png

The default Preview mode uses the optimized variants of the VB runtime and JET libraries. In this mode, all unnecessary characters (such as whitespaces and comments) in the application's source code are removed and variable names shortened to minify code and optimize performance.

The Debug Preview mode, on the other hand, uses the debug variants of the VB runtime and JET libraries. In this mode, line breaks and white spaces are preserved, allowing you to view the application's source code in a more readable format. You can then use your browser's debugging tools to step through your code and figure out exactly where an error occurred.

Because no performance optimization is done in debug mode, previewing an app in this mode can be misleading about how quickly—or slowly—an app opens. As a result, you might want to use debug mode only in a development environment.

  • To view your app like a user would with the pages and data displayed, click Preview.
  • To view your app in debug mode, click the Preview drop-down, select Debug Preview, then click Debug Preview icon.

Debug Business Objects

Because Visual Builder uses a multi-tier architecture, you might need to debug your application at different levels to identify the root cause of an issue. This might include the business object layer, where data access to and from a client application occurs through REST API endpoints.

While you can use the Network tab in your browser's development tools for external REST APIs, Visual Builder's built-in tracing and logging mechanisms can help you troubleshoot issues when you create business objects as the data source for your user interface. Because data from a business object is written to the UI via REST APIs, you might want to enable tracing to track the response times of individual REST calls. You can also enable logging to view events triggered by your business rules, in addition to diagnostic messages logged by custom Groovy scripts.

Enable Tracing to Monitor Endpoint Calls

When your application contains one or more business objects, enable tracing of an object's endpoint requests to diagnose performance bottlenecks in your application.

Tracing tracks all REST requests made when the current user executes CRUD operations or invoke functions on business objects. It provides a visual representation of the operations taking place and the time it took to invoke each REST call—information you can use to locate bottlenecks in your application. You also enable tracing separately for a particular version of your application (development, stage, or live), so you can isolate issues in that version and fine-tune your app for better performance.

To enable tracing for an application:

  1. Click Trace at the bottom of your application window.
  2. If your app has staged or live versions, select the version you want to enable tracing for.
  3. Click Enable Tracing.

    Once tracing is enabled, all REST requests made by the current user are traced, both when running the app using Preview or when making updates in the Data tab. If you selected a staged or live version of your app, endpoint requests made at runtime are traced. (You'll need to be the app designer or a team member assigned to the app to view traces for these runtime requests.)

    Click Refresh to view the latest traces.
    Description of tracing-enabled.png follows
    Description of the illustration tracing-enabled.png

    A trace is a collection of operations for an application transaction. When you edit business object data on a page (for example), your application interacts with the object's GET endpoint to request the data to display, and then with the PATCH endpoint to update the data. You'll see each endpoint request as a separate entry, with the time spent by your application processing the REST request shown in the Request Duration column.

    Note:

    In a cluster with multiple nodes, a REST API request (particularly one made by tools such as cURL or Postman) won't be traced if it was handled by a node other than the one on which you enabled tracing. To avoid this issue, make sure you use the browser on which you enabled tracing to also make your REST requests.
View Trace Details

You can view a particular REST request's trace for details such as span data and elapsed time. Each trace consists of one or more spans and you can drill down an individual trace to view its root span, which is the beginning of a transaction. You can also view Groovy logs if you included the print or println function in custom Groovy code.

To view details of an individual trace:

  1. Click the Details icon (Details icon) for the REST request you want to view.

    The REST request's tracing data is broken down and displayed in different tabs.

  2. Use the Spans and Top Elapsed tabs to view the request's tracing data.
    • The Spans view shows a Gantt chart that visually represents the steps in the REST request's execution path. You can hover your cursor over each step's bar graph to see the time the step took.

      To drill down and see details of a selected span and its children, click a span to select it, then right-click and select Top Elapsed of Selected Span to use the span as the context for the Top Elapsed view.

    • The Top Elapsed view shows operations performed during the request. Repetitive operations, for example, repeated calls to the same SQL Select statement or execution of the same Groovy function, are aggregated.

    You can filter operations in your Spans and Top Elapsed views by selecting Groovy or Database in the drop-down list when in the Spans or Top Elapsed tab.

  3. Click REST Request Info to view a summary of the REST request.
  4. If you included log messages in your Groovy scripts (for example, by adding print or println statements), click Groovy Logs to view the messages your script has generated.
Manage Tracing to Control Disk Usage

When tracing is enabled for an app, all its trace files are stored on Visual Builder server. To avoid disk-usage issues on the server's file system, Oracle sets a maximum disk space limit for all trace files. Once this limit is reached, the oldest trace files are removed to make way for new trace files.

Here are some options to help you manage your app's trace files:
  • Deselect the Enable Tracing check box to pause tracing. Use this option to control the accumulation of trace files when you're not actively tracking your app's REST calls.
  • Click the Export icon (Export icon) to export the trace files for an individual REST call. Use this option to save the files to your local file system and import it later when required. This way, you won't lose the data even if trace files hit the server's disk-usage limit.
  • Click the Delete icon (Delete icon) to delete trace files for individual REST calls. Use this option to remove trace files you don't need and clear up space.
  • Click Clear to remove all trace files for the app's current version. Use this option to delete tracing data for a particular version of an app. For example, when you're more interested in data for the staged and live versions of an app, you can clear trace files for the development version to remove previous data that might be taking up disk space on the server.
Export and Import a Trace File

You can export a particular REST call's trace files to your local file system to avoid losing data if the server reaches its disk-usage limit for trace files. Then, when you are ready to analyze the data, you can import the file back in to Visual Builder. Importing a trace file is a browser function that doesn't affect disk usage on the server.

To export and import a trace file:
  1. Click the Export icon (Export icon) for the REST call whose trace file you want to export.

    The trace file is saved as a .JSON file in the directory specified for your browser’s downloads.

  2. When you are ready to import the file back into the system, click Import From File in the drop-down list.
  3. Click the upload box and navigate to the .JSON file you previously exported. You can also drag and drop the file in the upload box.
    The file's contents display in the Trace panel. You can now view the trace's details and spans.

Enable Logging for Scripting Events

To assist with debugging when developing rules for a business object, you can enable logging and use the log viewer to view events triggered by your business rules. You can also view runtime exceptions as well as diagnostic messages that your own Groovy scripts might have generated.

While trigger starts and trigger ends are always recorded in logs, you'll need to add the print or println statement when you want messages in your script to be written to the log.

By default, logging is not enabled. Once you enable logging, it remains enabled in your session for as long as you are logged in. If your session has expired, you will need to re-enable logging after you log in.

To enable logging:
  1. Click the Logs link at the bottom of the window to open the Logs page.
  2. Select the Enable Logging check box.

    The viewer in the Logs window displays the most recent 250 log entries, by default in chronological order. When a runtime exception occurs, you can see additional details about the offending script and line number where the error occurred in a tooltip when you hover your mouse over the exception message.

    Use search to filter out messages based on the text you enter. To export your log as a text file to your local system, click the Export icon ( Export icon) in the toolbar.

    If you keep the Logs window open while you work, consider the following approach. Before starting a new attempt to reproduce the problem, click the Clear icon (Clear icon) to remove any previous messages generated. After encountering the error you are diagnosing, click the Refresh icon (Refresh icon) to see the latest log messages generated.

Note:

You can also view log messages included in your Groovy code as part of trace files generated for a business object's REST requests when tracing is enabled.