docs

BaseRock AI

Guidelines for Java Projects

Libraries required by BaseRock Plugin

In order to ensure successful test generation, the BaseRock Plugin mandates the presence of JUnit, Mockito, and Hamcrest libraries as dependencies in the source project.

Below are the steps to seamlessly integrate these dependencies into your project:

Junit Platform

BaseRock facilitates unit test generation across JUnit 5, JUnit 4, or TestNG platforms. The tool automatically identifies the JUnit version by inspecting the unit testing libraries declared in the project. If the project doesn’t currently employ any unit testing libraries, it’s necessary to include one of these libraries to enable seamless integration with BaseRock. If the project contains multiple JUnit libraries (e.g., JUnit 4 and TestNG), users have the option to set their preferred platform in the settings.

JUnit 5 introduced the concept of the JUnit Platform, which is a new foundation for running testing frameworks on the Java Virtual Machine (JVM). The JUnit Platform provides an execution environment for running tests and supports the creation of new testing frameworks. The JUnit Platform also introduced the concept of the JUnit Platform Launcher, which is responsible for discovering and executing tests on the platform.

The JUnit Platform supports different testing frameworks, and the term “engine” is often used to describe the individual components responsible for running tests written in a particular framework. For example:

JUnit Jupiter Engine: The engine that runs tests written using the JUnit Jupiter programming model.

JUnit Vintage Engine: The engine that runs tests written in JUnit 3 and JUnit 4 style.

Junit 5 Platform

BaseRock utilizes the JUnit Jupiter programming model for test code generation and employs the respective engine to execute and validate the tests if Junit 5 libraries have been included in the project. Following dependencies can be included for JUnit 5:

       testImplementation group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.9.2'
       testRuntimeOnly group: 'org.junit.jupiter', name: 'junit-jupiter-engine', version: '5.9.2'

Junit 4 Platform

BaseRock utilizes the JUnit 4 Vintage programming model for test code generation and employs the respective engine to execute and validate the tests if Junit 4 libraries have been included in the project. Following dependencies can be included for JUnit 4:

       testImplementation group: 'junit', name: 'junit', version: '4.13.2'

TestNG Platform

BaseRock utilizes the TestNG programming model for test code generation and employs the respective engine to execute and validate the tests if TestNG libraries have been included in the project.

For Java version 11 and higher:

Mockito Libraries ( JDK 11 and Above : 5.x)

Mockito is a library designed for creating mocks and stubs of objects, enabling isolation across logical layers in the code. To ensure compatibility with Java 11 or newer versions, it is recommended to use Mockito version 5.x or later.

For JDK 21, 22 (recommended mockito version 5.7.0, we need byte-buddy that is equal to or above 1.14.9 and so we exclude the byte-buddy that is shipped with mockito-inline) For JDK 23 (recommended mockito version 5.7.0, we need byte-buddy that is equal to or above 1.14.16 and so we exclude the byte-buddy that is shipped with mockito-inline)

       testImplementation group: 'org.mockito', name: 'mockito-core', version: '5.7.0'
       testImplementation group: 'org.mockito', name: 'mockito-inline', version: '5.2.0'{
		exclude group: 'net.bytebuddy', module: 'byte-buddy
	}
       // byte-buddy is an optional dependency. Mockito brings it, but an old version can cause problems. We need at least 1.14.16
       testImplementation group: 'net.bytebuddy', name: 'byte-buddy', version: '1.14.16'
       testImplementation group: 'org.mockito', name: 'mockito-core', version: '5.7.0'
       testImplementation group: 'org.mockito', name: 'mockito-inline', version: '5.2.0'{
		exclude group: 'net.bytebuddy', module: 'byte-buddy
	}
       // byte-buddy is an optional dependency. Mockito brings it, but an old version can cause problems. We need at least 1.14.9
       testImplementation group: 'net.bytebuddy', name: 'byte-buddy', version: '1.14.9'

For JDK 11 to JDK 20 (recommended mockito version 5.2.0)

       testImplementation group: 'org.mockito', name: 'mockito-core', version: '5.2.0'
       testImplementation group: 'org.mockito', name: 'mockito-inline', version: '5.2.0'
       // byte-buddy is an optional dependency. Mockito brings it, but an old version can cause problems. We need at least 1.12.9
       testImplementation group: 'net.bytebuddy', name: 'byte-buddy', version: '1.14.4'

Mockito is a library designed for creating mocks and stubs of objects, enabling isolation across logical layers in the code. To ensure compatibility with Java 8 version, it is recommended to use Mockito version 4.x or older.

       testImplementation group: 'org.mockito', name: 'mockito-core', version: '4.11.0'
       testImplementation group: 'org.mockito', name: 'mockito-inline', version: '4.11.0'
       // byte-buddy is an optional dependency. Mockito brings it, but an old version can cause problems. We need at least 1.12.9
       testImplementation group: 'net.bytebuddy', name: 'byte-buddy', version: '1.14.4'

Hamcrest Library

It brings substantial enhancements in terms of readability, expressiveness, composability, and error message reporting. For a detailed exploration of these advantages, you can refer to our blog post at: Understanding Hamcrest: Advantages and Disadvantages for Java Testing.

       testImplementation group: 'org.hamcrest', name: 'hamcrest', version: '3.0'

Spring boot Test Library

Spring Boot provides a number of utilities and annotations to help when testing your application.

       testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: "org.junit.jupiter", module: "junit-jupiter"
        exclude group: "org.mockito", module: "mockito-core"
        exclude group: "org.mockito", module: "mockito-junit-jupiter"
    }

OS Libraries

BaseRock AI Test Coder requires libgcc and libstdc++6 to be installed on linux before using the plugin. Please make sure these two packages are installed in your machine. For Ubuntu distribution you could install executing the following commands:

   sudo apt install libgcc-s1
   sudo apt install libstdc++6

Composable tests

Running Composable Tests with BaseRock.AI

To execute composable tests, our engine leverages built-in tasks provided by Android projects. To ensure smooth test execution, it’s important to verify that your Gradle project is correctly configured.

Verifying Your Project Configuration

Run the following commands to check if your project is properly configured:

./gradlew build
./gradlew :app:connectedDebugAndroidTest

If these commands execute without errors, your project is ready to run composable tests.

Test Location

Regular unit tests are generated in the test folder. Composable tests are generated in the androidTest folder.

Packaging options

When building an Android app, the packaging process merges resources and metadata from all libraries and dependencies into a single APK or AAB file. If multiple libraries include files with the same name and path (such as license files in the META-INF directory), this causes a conflict because the Android packaging system does not allow duplicate files. To resolve this, you need to use packagingOptions in your build.gradle to exclude these duplicate files. This ensures the build process completes successfully without including unnecessary metadata, which is typically not required for your app’s runtime functionality.

(AGP < 8.0):

android {
    packagingOptions {
        exclude "META-INF/licenses/**"
        exclude "META-INF/AL2.0"
        exclude "META-INF/LGPL2.1"
        exclude "META-INF/LICENSE.md"
        exclude "META-INF/LICENSE"
        exclude "META-INF/LICENSE-notice.md"
        exclude "META-INF/NOTICE"
        exclude "META-INF/*.md"
        exclude "META-INF/DEPENDENCIE"
    }
}

(AGP 8.0 and above):

android {
    packaging {
        resources {
            excludes += [
                "META-INF/licenses/**",
                "META-INF/AL2.0",
                "META-INF/LGPL2.1",
                "META-INF/LICENSE.md",
                "META-INF/LICENSE",
                "META-INF/LICENSE-notice.md",
                "META-INF/NOTICE",
                "META-INF/*.md",
                "META-INF/DEPENDENCIE"
            ]
        }
    }
}

Please assure you packaging options are fine, so our plugin will be able to execute the tests.

Enabling Coverage for BaseRock.AI Test Generation

To enable test coverage collection when using BaseRock.AI to generate composable tests, you need to configure your Gradle build file. Specifically, you must enable the testCoverageEnabled property in the debug build type.

Add the following snippet to your build.gradle file:

(AGP < 8.3):

android {
    buildTypes {
        debug {
            testCoverageEnabled true
        }
    }
}

(AGP 8.3 and above):

android {
    buildTypes {
        debug {
            enableUnitTestCoverage = true
            enableAndroidTestCoverage = true
        }
    }
}

Once this property is set, BaseRock.AI will collect test coverage data while generating tests, allowing you to measure and optimize your test coverage effectively.

Java Version Requirement

BaseRock supports unit test generation for project using Java Version 8 to 17 without any adjustments. However for Java 18 or later versions, configuring Intellij IDEA is required to boot up with the respective versions, as described below.

Supporting projects with a java version 18 or later

The current IntelliJ version (2024.1) defaults to boot up with Java 17, which may limit plugins’ ability to interpret and process classes generated using Java 18 or later versions.

Please follow below instructions to update the Java Runtime in IntelliJ.

- In the main menu, go to Help | Find Action
- Find and select the Choose Boot Java Runtime for the IDE action.
- Select the new desired runtime ex: JetBrains Runtime JBR (vanilla).
- Click OK.
- If necessary, you can change the location where IntelliJ IDEA will download the selected runtime.
- Wait for IntelliJ IDEA to restart with the new runtime.
- This adjustment should help mitigate the JVM crash issue until the official fix is released.

alt text

Intellij’s Official documentation available here official guide to change the default Java version for IntelliJ boot-up.

Fixing Java Version

Following steps are required to fix the java version in the project:

Cyclomatic Complexity

The cyclomatic complexity of a section of source code is a quantitative measure indicating the number of linearly independent paths within it. This metric is derived by constructing a Control Flow Graph of the code, effectively quantifying the number of linearly independent paths through a given program module. It’s labeled as LOW, MEDIUM or HIGH based on number of independent paths.

Disabled Generated Tests

When a method under test involves system calls, there’s a potential for adverse effects such as program termination, thread hang, or file/directory deletion. To mitigate risks, we identify and flag such potentially harmful calls by adding @Disabled to the generated test. By default, these tests won’t be executed. Users are encouraged to review test details and may choose to remove @Disabled if they determine the test is safe.

For example, the test generated may look like this:

    //Sapient generated method id: ${3f698e62-d52c-38cd-bce6-39784a59918a}
    @Disabled(value = "Potential harmful system call (System.exit) detected; Learn more: https://github.com/Sapient-AI/docs#disabled-test-due-to")
    @Test()
    void myMethodWhenParam() {
        /* Branches:
         * (param) : true
         */
        TestSystemExit target = new TestSystemExit();
        String result = target.myMethod(true);
        assertAll("result", () -> assertThat(result, equalTo("!")));
    }

The following Java functions are considered potentially dangerous, and if detected during test generation, @Disabled will be added to the test.

Batch Generation

BaseRock offers a robust feature enabling the specification of one or multiple source folders for unit test code generation. These folders yield numerous classes, each of which is meticulously analyzed and processed to generate test code. BaseRock methodically examines every method within these classes, compiling a comprehensive list of test cases and associating them with their respective test methods. Notably, certain methods, such as main methods for launching applications or getters/setters for data access, are purposefully excluded. This ensures that unit test code generation remains focused on functional code and avoids unnecessary code sprawl.

Main Method

Main method is used to launch Java application, start server or setup infrastructure elements, so it has been excluded from unit testing.

Getters and Setters Methods

Getters and Setters are standard methods used to maintain the state in a Java class. These are devoid of programming complexity, so they have been excluded from unit testing.

Equals, hashCode, wait, notify, waitAll, notifyAll etc.

Common object methods such as equals, hashCode, wait, notify, waitAll, notifyAll etc. are excluded from unit testing.

Troubleshooting

Byte buddy minimal version

If you face the following issue when running the tests, please make sure the version of byte-buddy is 1.12.9 or later

    Could not initialize plugin: interface org.mockito.plugins.MockMaker
    Caused by: org.mockito.exceptions.base.MockitoInitializationException:
    It seems like you are running Mockito with an incomplete or inconsistent class path. Byte Buddy could not be loaded.
    Byte Buddy is available on Maven Central as 'net.bytebuddy:byte-buddy' with the module name 'net.bytebuddy'.

Crashing Intellij build version 233 (2023.3) and Jetbrains Runtime 17 with JCFE

Some IntelliJ users have encountered JVM crashes when using IntelliJ 2023.3 with JetBrains 17 and JCFE, which is the default option upon installing an IntelliJ version, as reported here IDEA-340379.

JetBrains has already acknowledged and scheduled to release the fix in the 2024 release. Till then, users are recommended to change the JRE that IntelliJ uses from the version with JCFE to the vanilla version.

Please refer to instructions mentioned in section Supporting projects with a java version 18 or later

Unable to update build.gradle/build.gradle.kts/pom.xml

In case of a message like Unable to update build.gradle.kts. Please update with these instructions we are usually not able to find the build files because of:

Guidelines for Python Projects

Requirements

To ensure the proper functioning of the BaseRock AI VS Code extension, please ensure the following requirements are met:

If you encounter any errors while setting up the environment, follow these steps:

Ensure Python is Installed and Accessible

Check Virtual Environment Setup

Review the Output Panel in VS Code

Restart VS Code and Retry Setup

Additional Help

If you continue to experience issues after following these steps, please:

  1. Ensure all system requirements are met
  2. Check your Python version compatibility
  3. Verify all required dependencies are installed
  4. Contact support with detailed error messages if problems persist

Common Issues and Solutions

Python Not Found

# Add Python to PATH (Windows)
# Add to Environment Variables -> System Variables -> Path:
C:\Users\YourUsername\AppData\Local\Programs\Python\Python3x\
C:\Users\YourUsername\AppData\Local\Programs\Python\Python3x\Scripts\

# Add Python to PATH (MacOS)
# zsh - default shell for macOS Catalina and later
echo 'export PATH="/usr/local/bin:/usr/local/opt/Python3x/libexec/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Virtual Environment Activation Fails

# Windows PowerShell may need to run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Try alternative activation on Windows:
.\.venv\Scripts\activate.bat

Remember to replace Python3x with your specific Python version number.

Guidelines for JavaScript & TypeScript Projects

Prerequisites

Before using the BaseRock AI VS Code extension, ensure the following requirements are met:

1. Testing Framework Configuration

2. Test File Configuration

3. Framework-Specific Requirements

Depending on your project type, install the required testing utilities:

4. Install Dependencies

Troubleshooting

Unable to Sign In?

If you are experiencing issues signing in, follow these steps:

  1. When the Sign In prompt appears at the bottom right of VS Code, click Proceed.
  2. This will open your default browser, where you can select a preferred sign-in method.
  3. For the best experience, use Google Chrome or Mozilla Firefox.
    • If a different browser opens automatically, copy the URL and paste it into Chrome or Firefox to proceed.

Test Generation Issues

1. Verify Testing Framework Installation

2. Verify test file location

3. Ensure VS Code has access to the workspace

Tests Execution Issues

1. Confirm that the test runner is working

2. Check testCommand configuration

BaseRock Settings

CodeLens Implementation

1. Ensure file type is supported

2. Check VS Code settings

BaseRock with Cursor IDE

BaseRock plugin can be installed with cursor IDE. The minimum version for the support is 0.45.14.


Support

For additional assistance, please contact our support team: