diff --git a/src/content/docs/tutorials/javareporter/img/codebaseDiff.png b/src/content/docs/tutorials/javareporter/img/codebaseDiff.png new file mode 100644 index 00000000..0e802527 Binary files /dev/null and b/src/content/docs/tutorials/javareporter/img/codebaseDiff.png differ diff --git a/src/content/docs/tutorials/javareporter/img/firstSyncConsoleResult.png b/src/content/docs/tutorials/javareporter/img/firstSyncConsoleResult.png new file mode 100644 index 00000000..f1ae4f9b Binary files /dev/null and b/src/content/docs/tutorials/javareporter/img/firstSyncConsoleResult.png differ diff --git a/src/content/docs/tutorials/javareporter/img/uiImportResult.png b/src/content/docs/tutorials/javareporter/img/uiImportResult.png new file mode 100644 index 00000000..cafaffde Binary files /dev/null and b/src/content/docs/tutorials/javareporter/img/uiImportResult.png differ diff --git a/src/content/docs/tutorials/javareporter/junit.md b/src/content/docs/tutorials/javareporter/junit.md new file mode 100644 index 00000000..77c638f9 --- /dev/null +++ b/src/content/docs/tutorials/javareporter/junit.md @@ -0,0 +1,225 @@ +--- +title: JUnit Integration with Testomat.io +description: Learn how to integrate JUnit with Testomat.io using Java-Reporter for efficient test management and detailed reporting. This guide covers adding Maven/Gradle dependencies, importing JUnit tests, configuring Java-Reporter properties, and customizing test runs for seamless test reporting workflows. +type: article +url: https://docs.testomat.io/tutorials/javareporter/junit +head: + - tag: meta + attrs: + name: keywords + content: JUnit integration, Testomat.io, Java-Reporter, JUnit tests, test reporting, Maven dependency, Gradle dependency, test management, Java test automation, test run customization, test properties configuration +--- + + + +# JUnit integration with Testomat.io + +This guide demonstrates how to integrate JUnit with [Testomat.io](https://app.testomat.io) for efficient test management +and detailed reporting. + +--- + +## Adding the dependency + +Add the proper **Maven/Gradle** snippet to your **pom.xml/build.gradle** file. + +```xml + + + io.testomat + java-reporter-junit + 0.7.4 + +``` + +```properties + implementation group: 'io.testomat', name: 'java-reporter-junit', version: '0.7.4' +``` + +> NOTE: There might be an updated version of the library published. You can check it in +> the [Maven Central Repository](https://central.sonatype.com/artifact/io.testomat/java-reporter-junit) + +--- + +## Importing JUnit tests to [Testomat.io](https://app.testomat.io) + +Before using the reporter, your tests codebase should be imported to the [Testomat.io](https://app.testomat.io) server. +This will allow the server to process your run results and tests structure properly, and also it will allow you to see the +test methods source code io the UI. +The importing is possible with Java-Check-Tests CLI - a convenient CLI that allows to sync you codebase with server, add/update IDs +and clean IDs from codebase if you don't need them. +Its repository can be found [here](https://github.com/testomatio/java-check-tests/tree/main). + +***It is important to sync your tests with the Testomat.io server to create proper test folder structure and +to be able to see the source code of your tests in the UI*** + + +>**Prerequisites:** +Reporter dependency is added to your project. + +--- +### Synchronizing your test codebase +By default, this will import ***all*** the tests from the directory you run the query in and recursively from all the directories +inside. To change the directory, use the `--directory` property (see below). +There is a convenient way to do this in one move - use the oneliners that will download the latest version of +**java-check-tests** and run the `sync`(or use `update-ids` alias if you wish) command. +Here is one for UNIX/MAC users: +```bash + export TESTOMATIO=... && \ + curl -L -O https://github.com/testomatio/java-check-tests/releases/latest/download/testomatio.jar && \ + java -jar testomatio.jar sync +``` +And this one is for Windows users: +```cmd + set TESTOMATIO=...&& ^ + curl -L -O https://github.com/testomatio/java-check-tests/releases/latest/download/testomatio.jar&& ^ + java -jar testomatio.jar sync +``` + +`TESTOMATIO` is your project API key that you can get from **Testomat.io > Account > Access-Tokens**. +You can add `export TESTOMATIO_URL=... && \` or `set TESTOMATIO_URL=...&& ^ \` depending on your OS if the default url +https://app.testomat.io needs to be changed. +Troubleshooting: check if you haven't missed any whitespaces while editing the query. + +>**NOTE**: This command will download the jar file **testomatio.jar** to the directory from which you run the query. +>This file will remain in the directory and ***won't be removed automatically***. + +After you run this command, here is what you are supposed to see: +> **In the terminal:** +> +First sync command run console result image + +> **In the Testomat.io UI:** +> +UI import result image + +> **In your test classes:** +> +Codebase diff image after sync + +If you already have the `testomatio.jar` in the directory and need to sync again, run this: + +```bash + java -jar testomatio.jar sync --apikey=... +``` +`--apikey` is not required if you did not restart the terminal session. +`--url` might be used if you use different url than https://app.testomat.io +### What it does implicitly: +The `sync` command runs `import` and `pull-ids` consecutively after import succeeds. +The **import** command parses your codebase and imports it to Testomat.io. +The **pull-ids** command adds or updates the @TestId annotations to your test methods and related imports to the test classes. + +--- + +### Command options +Optionally, you can use a property for the CLI to search for tests in another directory by providing: +- `--directory=./relative/path/from/current`. This option works for other commands as well. +--- + +### Other commands +Since the `testomatio.jar` is already in your project, you can use other commands: +> `java -jar testomatio clean-ids` +> +This command will remove all the IDs from test methods and related imports from the test classes. +`--directory` works for this command. +If you have already removed the jar from the project, you can run the oneliner you used to sync, +but change `sync` to `clean-ids`. +
+
+ + +>`java -jar testomatio import` +> +This allows you to import your codebase to Testomat.io without adding/updating the IDs. +`--apikey` is not required if you did not restart the terminal session. +`--url` might be used if you use different url than https://app.testomat.io +
+
+ +As you can see, the Java-Check-Tests usage is pretty straightforward. +If you need more information, have any suggestions, or encounter any problems with this CLI, create an issue in its repository: [Java-check-tests repository](https://github.com/testomatio/java-check-tests/tree/main) +As importing is completed - let's step forward to the Java-Reporter configuration! + +--- + +## Configure Java-Reporter in your project + +1. If you don't have the **junit-platform.properties** file in your `resources` folder, create it and add this line: + `junit.jupiter.extensions.autodetection.enabled=true` + + This will activate the service loader mechanism on your project side to allow running the library, as it's based on the JUnit + extension. +

+ +2. You will need to provide some properties for reporting. + The list of required properties is quite short: + - `testomatio.listening=true` – enables the reporting as a whole. + - `testomatio.api.key` – the particular project API key you can obtain in [Testomat.io](https://app.testomat.io) > + Account > Access-Tokens + + There are four ways to provide properties: + - System environment + - JVM properties + - `testomatio.properties` file in the resources folder + - `testomatio.url=https://beta.testomat.io` – if you run on beta, add this property as the library reports to + https://app.testomat.io + + The most reliable and convenient way is to use the properties file. + + > - If you use the **JVM-properties** approach, use the **dot notation** (`testomatio.api.key`) + + > - When using environment variables, write properties in constant case (`TESTOMATIO_API_KEY`) + + > Names of the properties **remain the same** in both approaches. + +3. When you have synchronized your code and provided the required properties, that's basically all: run your tests and see + the results in the [Testomat.io UI](https://app.testomat.io) + + - ***Run customization with additional properties*** + + | Setting | What it does | Default | Example | + |----------------------------|---------------------------------------|---------------------|------------------------------| + | **`testomatio.run.title`** | Custom name for your test run | `default_run_title` | `"Nightly Regression Tests"` | + | **`testomatio.env`** | Environment name (dev, staging, prod) | _(none)_ | `"staging"` | + | **`testomatio.run.group`** | Group related runs together | _(none)_ | `"sprint-23"` | + | **`testomatio.publish`** | Make results publicly shareable | _(private)_ | `1` | + + - Advanced customization + + | Setting | What it does | Example | + |-------------------------------------|-------------------------------------------------------------|----------------------------| + | **`testomatio.url`** | Custom Testomat.io URL (for enterprise) | `https://app.testomat.io/` | + | **`testomatio.run.id`** | Add results from current run to another that already exists | `"run_abc123"` | + | **`testomatio.create`** | Auto-create missing tests in Testomat.io | `true` | + | **`testomatio.shared.run`** | Shared run name for team collaboration | `"team-integration-tests"` | + | **`testomatio.shared.run.timeout`** | How long to wait for shared run (seconds) | `3600` | + | **`testomatio.export.required`** | Exports your test code to Testomat.io | `true` | + +4. As you can see, there is the `testomatio.export.required` property in the list. + It allows you to sync the codebase with [Testomat.io](https://app.testomat.io), but in a slightly different way + than the [Java-Check-Tests CLI](https://github.com/testomatio/java-check-tests). + It will also import your test codebase but ***when you run tests*** and ***only the tests in this run***. + +### If you need more information, have any suggestions, or encounter any problems with Java Reporter, create an issue in its repository: [Java-Reporter repository](https://github.com/testomatio/java-reporter/tree/1.x) \ No newline at end of file diff --git a/src/content/docs/tutorials/javareporter/testng.md b/src/content/docs/tutorials/javareporter/testng.md new file mode 100644 index 00000000..012db560 --- /dev/null +++ b/src/content/docs/tutorials/javareporter/testng.md @@ -0,0 +1,218 @@ +--- +title: TestNG Integration with Testomat.io +description: Learn how to integrate TestNG with Testomat.io using Java-Reporter for efficient test management and detailed reporting. This guide covers adding Maven/Gradle dependencies, importing TestNG tests, configuring Java-Reporter properties, and customizing test runs for seamless test reporting workflows. +type: article +url: https://docs.testomat.io/tutorials/javareporter/testng +head: + - tag: meta + attrs: + name: keywords + content: TestNG integration, Testomat.io, Java-Reporter, TestNG tests, test reporting, Maven dependency, Gradle dependency, test management, Java test automation, test run customization, test properties configuration +--- + + + +# TestNG integration with Testomat.io + +This guide demonstrates how to integrate TestNG with [Testomat.io](https://app.testomat.io) for efficient test management +and detailed reporting. + +--- + +## Adding the dependency + +Add the proper **Maven/Gradle** snippet to your **pom.xml/build.gradle** file. + +```xml + + + io.testomat + java-reporter-testng + 0.7.4 + +``` + +```properties + implementation group: 'io.testomat', name: 'java-reporter-testng', version: '0.7.4' +``` + +> NOTE: There might be an updated version of the library published. You can check it in +> the [Maven Central Repository](https://central.sonatype.com/artifact/io.testomat/java-reporter-testng) + +--- + +## Importing JUnit tests to [Testomat.io](https://app.testomat.io) + +Before using the reporter, your tests codebase should be imported to the [Testomat.io](https://app.testomat.io) server. +This will allow the server to process your run results and tests structure properly, and also it will allow you to see the +test methods source code io the UI. +The importing is possible with Java-Check-Tests CLI - a convenient CLI that allows to sync you codebase with server, add/update IDs +and clean IDs from codebase if you don't need them. +Its repository can be found [here](https://github.com/testomatio/java-check-tests/tree/main). + +***It is important to sync your tests with the Testomat.io server to create proper test folder structure and +to be able to see the source code of your tests in the UI*** + + +>**Prerequisites:** +Reporter dependency is added to your project. + +--- +### Synchronizing your test codebase +By default, this will import ***all*** the tests from the directory you run the query in and recursively from all the directories +inside. To change the directory, use the `--directory` property (see below). +There is a convenient way to do this in one move - use the oneliners that will download the latest version of +**java-check-tests** and run the `sync`(or use `update-ids` alias if you wish) command. +Here is one for UNIX/MAC users: +```bash + export TESTOMATIO=... && \ + curl -L -O https://github.com/testomatio/java-check-tests/releases/latest/download/testomatio.jar && \ + java -jar testomatio.jar sync +``` +And this one is for Windows users: +```cmd + set TESTOMATIO=...&& ^ + curl -L -O https://github.com/testomatio/java-check-tests/releases/latest/download/testomatio.jar&& ^ + java -jar testomatio.jar sync +``` + +`TESTOMATIO` is your project API key that you can get from **Testomat.io > Account > Access-Tokens**. +You can add `export TESTOMATIO_URL=... && \` or `set TESTOMATIO_URL=...&& ^ \` depending on your OS if the default url +https://app.testomat.io needs to be changed. +Troubleshooting: check if you haven't missed any whitespaces while editing the query. + +>**NOTE**: This command will download the jar file **testomatio.jar** to the directory from which you run the query. +>This file will remain in the directory and ***won't be removed automatically***. + +After you run this command, here is what you are supposed to see: +> **In the terminal:** +> +First sync command run console result image + +> **In the Testomat.io UI:** +> +UI import result image + +> **In your test classes:** +> +Codebase diff image after sync + +If you already have the `testomatio.jar` in the directory and need to sync again, run this: + +```bash + java -jar testomatio.jar sync --apikey=... +``` +`--apikey` is not required if you did not restart the terminal session. +`--url` might be used if you use different url than https://app.testomat.io +### What it does implicitly: +The `sync` command runs `import` and `pull-ids` consecutively after import succeeds. +The **import** command parses your codebase and imports it to Testomat.io. +The **pull-ids** command adds or updates the @TestId annotations to your test methods and related imports to the test classes. + +--- + +### Command options +Optionally, you can use a property for the CLI to search for tests in another directory by providing: +- `--directory=./relative/path/from/current`. This option works for other commands as well. +--- + +### Other commands +Since the `testomatio.jar` is already in your project, you can use other commands: +> `java -jar testomatio clean-ids` +> +This command will remove all the IDs from test methods and related imports from the test classes. +`--directory` works for this command. +If you have already removed the jar from the project, you can run the oneliner you used to sync, +but change `sync` to `clean-ids`. +
+
+ + +>`java -jar testomatio import` +> +This allows you to import your codebase to Testomat.io without adding/updating the IDs. +`--apikey` is not required if you did not restart the terminal session. +`--url` might be used if you use different url than https://app.testomat.io +
+
+ +As you can see, the Java-Check-Tests usage is pretty straightforward. +If you need more information, have any suggestions, or encounter any problems with this CLI, create an issue in its repository: [Java-check-tests repository](https://github.com/testomatio/java-check-tests/tree/main) +As importing is completed - let's step forward to the Java-Reporter configuration! + +--- + +## Configure Java-Reporter in your project + +1. You will need to provide some properties for reporting. + The list of required properties is quite short: + - `testomatio.listening=true` – enables the reporting as a whole. + - `testomatio.api.key` – the particular project API key you can obtain in [Testomat.io](https://app.testomat.io) > + Account > Access-Tokens + + There are four ways to provide properties: + - System environment + - JVM properties + - `testomatio.properties` file in the resources folder + - `testomatio.url=https://beta.testomat.io` – if you run on beta, add this property as the library reports to + https://app.testomat.io + + The most reliable and convenient way is to use the properties file. + + > - If you use the **JVM-properties** approach, use the **dot notation** (`testomatio.api.key`) + + > - When using environment variables, write properties in constant case (`TESTOMATIO_API_KEY`) + + > Names of the properties **remain the same** in both approaches. + +2. When you have synchronized your code and provided the required properties, that's basically all: run your tests and see + the results in the [Testomat.io UI](https://app.testomat.io) + + - ***Run customization with additional properties*** + + | Setting | What it does | Default | Example | + |----------------------------|---------------------------------------|---------------------|------------------------------| + | **`testomatio.run.title`** | Custom name for your test run | `default_run_title` | `"Nightly Regression Tests"` | + | **`testomatio.env`** | Environment name (dev, staging, prod) | _(none)_ | `"staging"` | + | **`testomatio.run.group`** | Group related runs together | _(none)_ | `"sprint-23"` | + | **`testomatio.publish`** | Make results publicly shareable | _(private)_ | `1` | + + - Advanced customization + + | Setting | What it does | Example | + |-------------------------------------|-------------------------------------------------------------|----------------------------| + | **`testomatio.url`** | Custom Testomat.io URL (for enterprise) | `https://app.testomat.io/` | + | **`testomatio.run.id`** | Add results from current run to another that already exists | `"run_abc123"` | + | **`testomatio.create`** | Auto-create missing tests in Testomat.io | `true` | + | **`testomatio.shared.run`** | Shared run name for team collaboration | `"team-integration-tests"` | + | **`testomatio.shared.run.timeout`** | How long to wait for shared run (seconds) | `3600` | + | **`testomatio.export.required`** | Exports your test code to Testomat.io | `true` | + +3. As you can see, there is the `testomatio.export.required` property in the list. + It allows you to sync the codebase with [Testomat.io](https://app.testomat.io), but in a slightly different way + than the [Java-Check-Tests CLI](https://github.com/testomatio/java-check-tests). + It will also import your test codebase but ***when you run tests*** and ***only the tests in this run***. + +### If you need more information, have any suggestions, or encounter any problems with Java Reporter, create an issue in its repository: [Java-Reporter repository](https://github.com/testomatio/java-reporter/tree/1.x) \ No newline at end of file