Debugging your Application

While you are developing your Equo application, or any other application that consumes Equo Chromium, you will likely run into some problems that require debugging.

Equo Debug automates the debugging of Equo apps and Equo Chromium and integrates with Devtools and framework specific debugging tools (like Vue).

Since an Equo application consists of two big parts, the Java and the JavaScript parts, you will need to use one of the the following approaches depending on your development environment.

First Step

To consume Equo Debug, you have to add the new dependency as follow, depending on the build framework you have used:

Maven

<dependency>
    <groupId>com.equo</groupId>
    <artifactId>com.equo.debug.bom</artifactId>
    <version>${latest}</version>
</dependency>

Gradle Groovy

implementation 'com.equo:com.equo.debug.bom:${latest}'

Grade Kotlin

implementation("com.equo:com.equo.debug.bom:${latest}")

It is recommended to use the latest version of Equo Debug. Please refer to this link to find the latest version.

Debugging Java in your IDE

When you are developing your application that consumes Equo Chromium, like an Equo application, you will end up running it as a normal Java application. To debug it in your favorite IDE, you just need to run your application in debug mode.

Debugging Java with the Equo CLI

To debug Java in an Equo Application with the CLI, you just have to run your application with the equo debug command. This generates a remote connection to be able to link with java and be able to correctly debug your application. The default port generated for Java is 8000. But of course you can choose the port you want, simply by using the --java.port flag.

Examples:

# To set the default java port for debug
equo debug your-application

# To set a specific java port for debug
equo debug your-application --java.port 7777

Then you can set the same port for debugging in your favourite IDE

Debug and DevTools from your IDE

To debug JavaScript, HTML, and CSS in your IDE you have to run the app with the chromium.debug_port property, specifying the port for remote debugging. This will also print logs in the console.

The property could be added as VM arguments in your IDE, or set as system property in java.

It is also possible to set the property as auto. This automatically opens an available port for devtools and debug.

Examples:

-Dchromium.debug_port="8888"

-Dchromium.debug_port="auto"

Or as Java System Property:

System.setProperty("chromium.debug_port", "8888");

System.setProperty("chromium.debug_port", "auto");

You must make sure you have the property before running the application EquoApp.launch();

Then it will open a browser (i.e. Chrome). You can also enter the following URL in your favorite browser and see all the available browsers of your application to debug:

localhost:8888

There, you can inspect your application elements. Note that to debug JavaScript your Equo application must be already running.

Vue DevTools from your IDE

You can also debug using Vue Devtools.

Configuration of the Property to Debug Vue Devtools

In addition to passing the chromium.debug_port property as a VM argument as we have seen before, it is necessary to add the vue.port property as a VM argument, specifying the port that the Vue server opens for development. Equo will attempt to run the Vue development server automatically, but if it is not possible, it will be requested to run the server manually.

To manually run the Vue server in an Equo application that uses the Vue framework and Vite package manager, you need to go to the your-application/src/main/ui directory and execute the following command to open the Vue development server.

npm run dev

This is an example for an Equo application that uses Vite, and the command seen above npm run dev opens the development server on port 5173. But if you use a different package manager, you can still start the server manually by navigating to the directory where the package.json file is located.

The following example is necessary to properly connect to the server in an Equo application using a VM argument in Java. However, it is important to set the correct port for the property.

Example:

-Dvue.port=5173

Alternatively, you can configure the property as a System Property in Java.

Example:

System.setProperty("vue.port", "5173");

You must make sure you have the property before running the application EquoApp.launch();

Debug and DevTools from the Equo CLI

To debug JavaScript, HTML, and CSS from the Equo CLI, you have to execute the equo debug command. To specify the port for remote debugging you can add the flag --chromium.debug_port, otherwise it will be automatically configured. This will also print logs in the console.

Examples:

# To set a random chromium port for debug
equo debug your-application

# To set a specific chromium port for debug
equo debug your-application --chromium.debug_port 8888

There, you can inspect your application elements. This command will execute the equo application and open Devtools.

Vue DevTools from the Equo CLI

If you want to run a Vue application in debug mode, the Equo CLI will automatically prompt you to open Vue Devtools Standalone.

Configuration of the Property to Debug Vue Devtools

It is also possible to run the application directly in debug mode with the following arguments.

Examples:

# To set a random chromium port for debugging and open vue devtools standalone
equo debug your-application --vue.port 5173

# To set a specific chromium port for debug and open vue devtools standalone
equo debug your-application --chromium.debug_port 8888 --vue.port 5173

The port needs to be the development server that the package manager of your Vue application opens. For Equo applications, it uses the Vite package manager, which opens port 5173 as mentioned here.