diff --git a/build.gradle b/build.gradle index 108a5c4..8a92779 100644 --- a/build.gradle +++ b/build.gradle @@ -41,3 +41,6 @@ spotless { } } +javadoc { + options.tags = [ "implNote:a:Implementation Note:" ] +} diff --git a/src/main/java/io/github/lambdatest/gradle/AppUploader.java b/src/main/java/io/github/lambdatest/gradle/AppUploader.java index adab680..4ce322d 100644 --- a/src/main/java/io/github/lambdatest/gradle/AppUploader.java +++ b/src/main/java/io/github/lambdatest/gradle/AppUploader.java @@ -5,6 +5,13 @@ import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; +/** + * Handles the asynchronous upload of application files to the LambdaTest platform. This class + * manages the upload process and returns the application ID for test execution. + * + *

Uses {@link UploaderUtil#uploadAndGetId(String, String, String)} for the actual file upload + * process. + */ public class AppUploader { private static final Logger logger = LogManager.getLogger(AppUploader.class); @@ -13,6 +20,13 @@ public class AppUploader { private String accessKey; private String appFilePath; + /** + * Creates a new AppUploader instance with the specified credentials and file path. + * + * @param username The LambdaTest account username + * @param accessKey The LambdaTest account access key + * @param appFilePath The path to the application file to be uploaded + */ public AppUploader(String username, String accessKey, String appFilePath) { if (username == null) throw new IllegalArgumentException("Username cannot be null"); if (accessKey == null) throw new IllegalArgumentException("Access Key cannot be null"); @@ -23,6 +37,13 @@ public AppUploader(String username, String accessKey, String appFilePath) { this.appFilePath = appFilePath; } + /** + * Uploads the application file asynchronously to LambdaTest. + * + * @implNote Uses CompletableFuture to perform the upload asynchronously, allowing parallel + * processing of other tasks. + * @return A CompletableFuture that resolves to the uploaded application's ID + */ public CompletableFuture uploadAppAsync() { return CompletableFuture.supplyAsync( () -> { diff --git a/src/main/java/io/github/lambdatest/gradle/Constants.java b/src/main/java/io/github/lambdatest/gradle/Constants.java index e05ed58..f67f673 100644 --- a/src/main/java/io/github/lambdatest/gradle/Constants.java +++ b/src/main/java/io/github/lambdatest/gradle/Constants.java @@ -1,6 +1,11 @@ package io.github.lambdatest.gradle; +/** + * Constants used throughout the LambdaTest Gradle plugin. This utility class provides centralized + * access to API endpoints and other constant values. + */ public class Constants { + /** Private constructor to prevent instantiation of this utility class. */ private Constants() { throw new UnsupportedOperationException( "This is a utility class and cannot be instantiated"); diff --git a/src/main/java/io/github/lambdatest/gradle/LambdaTestPlugin.java b/src/main/java/io/github/lambdatest/gradle/LambdaTestPlugin.java index 6dd290b..a025d61 100644 --- a/src/main/java/io/github/lambdatest/gradle/LambdaTestPlugin.java +++ b/src/main/java/io/github/lambdatest/gradle/LambdaTestPlugin.java @@ -3,8 +3,17 @@ import org.gradle.api.Plugin; import org.gradle.api.Project; +/** + * The main plugin class that integrates LambdaTest functionality into the Gradle build system. This + * plugin adds the 'runLambdaTest' task to the project's task container. + */ public class LambdaTestPlugin implements Plugin { + /** + * Applies the plugin to the specified Gradle project, registering the LambdaTest task. + * + * @param project The Gradle project to which this plugin is being applied + */ @Override public void apply(Project project) { // Register a new task named "runLambdaTest" and associate it with the LambdaTestTask class diff --git a/src/main/java/io/github/lambdatest/gradle/LambdaTestTask.java b/src/main/java/io/github/lambdatest/gradle/LambdaTestTask.java index 405bab4..44af815 100644 --- a/src/main/java/io/github/lambdatest/gradle/LambdaTestTask.java +++ b/src/main/java/io/github/lambdatest/gradle/LambdaTestTask.java @@ -11,6 +11,14 @@ import org.gradle.api.DefaultTask; import org.gradle.api.tasks.TaskAction; +/** + * Main task class for the LambdaTest Gradle plugin that handles test execution on the LambdaTest + * platform. This task manages the upload of applications and test suites, followed by test + * execution with specified configurations. + * + *

This task coordinates between {@link AppUploader}, {@link TestSuiteUploader}, and {@link + * TestExecutor} to manage the complete test execution lifecycle. + */ public class LambdaTestTask extends DefaultTask { private static final Logger logger = LogManager.getLogger(LambdaTestTask.class); @@ -38,6 +46,16 @@ public class LambdaTestTask extends DefaultTask { private String testSuiteId; private Integer queueTimeout; + /** + * Executes the LambdaTest task, which includes uploading the application and test suite, + * followed by test execution on the LambdaTest platform. + * + * @implNote This method handles the task execution in three main phases: 1. Asynchronous upload + * of the application using {@link AppUploader#uploadAppAsync()} 2. Asynchronous upload of + * the test suite using {@link TestSuiteUploader#uploadTestSuiteAsync()} 3. Test execution + * with {@link TestExecutor#executeTests(Map)} + * @throws RuntimeException if any upload or test execution fails + */ @TaskAction public void runLambdaTest() { logger.info("Starting LambdaTest task..."); diff --git a/src/main/java/io/github/lambdatest/gradle/TestExecutor.java b/src/main/java/io/github/lambdatest/gradle/TestExecutor.java index e655371..e7ed5ee 100644 --- a/src/main/java/io/github/lambdatest/gradle/TestExecutor.java +++ b/src/main/java/io/github/lambdatest/gradle/TestExecutor.java @@ -9,6 +9,12 @@ import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; +/** + * Manages the execution of tests on the LambdaTest platform. This class handles the test execution + * configuration and communication with the LambdaTest API. + * + *

Uses endpoints defined in {@link Constants} for API communication. + */ public class TestExecutor { private static final Logger logger = LogManager.getLogger(TestExecutor.class); @@ -19,6 +25,16 @@ public class TestExecutor { private List device; private Boolean isFlutter; + /** + * Creates a new TestExecutor with the specified configuration. + * + * @param username The LambdaTest account username + * @param accessKey The LambdaTest account access key + * @param appId The ID of the uploaded application + * @param testSuiteId The ID of the uploaded test suite + * @param device List of target devices for test execution + * @param isFlutter Boolean indicating if this is a Flutter application + */ public TestExecutor( String username, String accessKey, @@ -34,6 +50,15 @@ public TestExecutor( this.isFlutter = isFlutter; } + /** + * Executes the tests on LambdaTest with the specified parameters. + * + * @implNote This method constructs the test capabilities and sends them to either {@link + * Constants#BUILD_URL} or {@link Constants#FLUTTER_BUILD_URL} based on whether it's a + * Flutter or standard application. + * @param params Map of additional test execution parameters + * @throws IOException if there's an error in communication with the LambdaTest API + */ public void executeTests(Map params) throws IOException { try { OkHttpClient client = new OkHttpClient(); diff --git a/src/main/java/io/github/lambdatest/gradle/TestSuiteUploader.java b/src/main/java/io/github/lambdatest/gradle/TestSuiteUploader.java index b78eb22..a91983e 100644 --- a/src/main/java/io/github/lambdatest/gradle/TestSuiteUploader.java +++ b/src/main/java/io/github/lambdatest/gradle/TestSuiteUploader.java @@ -5,6 +5,10 @@ import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; +/** + * Handles the asynchronous upload of test suite files to the LambdaTest platform. This class + * manages the upload process and returns the test suite ID for test execution. + */ public class TestSuiteUploader { private static final Logger logger = LogManager.getLogger(TestSuiteUploader.class); @@ -13,12 +17,26 @@ public class TestSuiteUploader { private String accessKey; private String testSuiteFilePath; + /** + * Creates a new TestSuiteUploader instance with the specified credentials and file path. + * + * @param username The LambdaTest account username + * @param accessKey The LambdaTest account access key + * @param testSuiteFilePath The path to the test suite file to be uploaded + */ public TestSuiteUploader(String username, String accessKey, String testSuiteFilePath) { this.username = username; this.accessKey = accessKey; this.testSuiteFilePath = testSuiteFilePath; } + /** + * Uploads the test suite file asynchronously to LambdaTest. + * + * @implNote Uses CompletableFuture to perform the upload asynchronously, allowing parallel + * processing of other tasks. + * @return A CompletableFuture that resolves to the uploaded test suite's ID + */ public CompletableFuture uploadTestSuiteAsync() { return CompletableFuture.supplyAsync( () -> { diff --git a/src/main/java/io/github/lambdatest/gradle/UploaderUtil.java b/src/main/java/io/github/lambdatest/gradle/UploaderUtil.java index 1d40950..6399452 100644 --- a/src/main/java/io/github/lambdatest/gradle/UploaderUtil.java +++ b/src/main/java/io/github/lambdatest/gradle/UploaderUtil.java @@ -12,14 +12,34 @@ import okhttp3.RequestBody; import okhttp3.Response; +/** + * Utility class providing common upload functionality for the LambdaTest Gradle plugin. This class + * handles the actual file upload process and response parsing. + * + *

This utility is used by both {@link AppUploader} and {@link TestSuiteUploader} to handle file + * uploads to the LambdaTest platform. + */ public final class UploaderUtil { + /** Private constructor to prevent instantiation of this utility class. */ private UploaderUtil() { throw new UnsupportedOperationException( "This is a utility class and cannot be instantiated"); } + /** + * Uploads a file to LambdaTest and returns its ID. + * + * @implNote This method sends the file to {@link Constants#API_URL} and handles the multipart + * form data construction and response parsing. + * @param username The LambdaTest account username + * @param accessKey The LambdaTest account access key + * @param filePath The path to the file to be uploaded + * @return The ID of the uploaded file + * @throws IOException if there's an error during file upload or response parsing + */ public static String uploadAndGetId(String username, String accessKey, String filePath) throws IOException { + OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/octet-stream");