> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/maven

Simplify common tasks for building and testing Java projects using Maven on CircleCI


## Commands

### process_test_results

Upload test results.
This will populate the Test Summary tab in the CircleCI UI. By default it will
look in `target/surefire-reports` (the default location for maven test results).
You can override where to find the test results with the path parameter.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app_src_directory` | string |  | The directory containing the pom.xml file for the project.
Useful when the source of your maven project is not in the root directory of your git repo.

This is ignored if test_results_path is an absolute path.
 |
| `test_results_path` | string | target/surefire-reports | Specify a custom path for maven test results |

### with_cache

Run a set of steps with Maven dependencies cached.

This command will first restore a cache of maven dependencies, if one was
saved by a previous build. The provided `steps` parameter will then be executed, and
if successful, then a fresh cache will be saved, if required.

The contents of the `~/.m2/repository` directory is cached, which will substantially
improve build times for projects with many dependencies.

The cache-key is generated from any files named `pom.xml` that are
present in the `working_directory`.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app_src_directory` | string |  | The directory containing the pom.xml file for the project.
Useful when the source of your maven project is not in the root directory of your git repo.
 |
| `cache_name` | string | maven | The cache's name prefix to allow for multiple caches and/or cache invalidation. |
| `checksum_location` | string | .maven_cache_seed | The path to save the checksum when calculating cache. |
| `dependency_plugin_version` | string | 3.1.2 | Specify the Maven Dependency Plugin |
| `maven_command` | string | mvn | Specify a custom path for invoking maven |
| `settings_file` | string |  | Specify a custom settings file to use (optional) |
| `steps` | steps |  |  |
| `verify_dependencies` | boolean | true | Verify dependencies are valid and available from public sources |

## Jobs

### parallel_test

Checkout, build, test, and upload test results for a Maven project spreading tests across multiple nodes


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app_src_directory` | string |  | The directory containing the pom.xml file for the project.
Useful when the source of your maven project is not in the root directory of your git repo.
 |
| `cache_name` | string | maven | The cache's name prefix to allow for multiple caches and/or cache invalidation. |
| `command` | string | verify | The maven command(s) to run. Multiple commands can be run by providing a multi-line string. |
| `dependency_plugin_version` | string | 3.1.2 | Specify the Maven Dependency Plugin |
| `executor` | executor | default | The name of custom executor to use |
| `maven_command` | string | mvn | Specify a custom path for invoking maven |
| `mvn_step_name` | string | Run Tests | The name given to the step that runs the maven command. |
| `parallel_it_pattern` | string | **/*IT*.java | This is the standard Failsafe pattern, but you can override
if you use alternate <includes> patterns in your pom.xml.
 |
| `parallel_test_pattern` | string | **/*Test*.java | This is the standard Surefire pattern, but you can override
if you use alternate <includes> patterns in your pom.xml
 |
| `parallelism` | integer | 2 | How many nodes should testing be split across? |
| `post_mvn_steps` | steps |  | (Optional) Steps to run immediately after maven has completed, before test results are processed. |
| `pre_mvn_steps` | steps |  | (Optional) Steps to run just before maven, after the code has been checked out and the cache has been restored. |
| `settings_file` | string |  | Specify a custom settings file to use (optional) |
| `skip_checkout` | boolean | false | Skip the checkout step if set to true. Useful when pre-steps are passed in to the job that will obtain the source code. |
| `test_directory` | string | src/test/java | If following standard maven conventions this does not need to be changed. |
| `test_results_path` | string | target/surefire-reports | The path to the test results. |
| `verify_dependencies` | boolean | true | Verify dependencies are valid and available from public sources |

### test

Checkout, build, test, and upload test results for a Maven project.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app_src_directory` | string |  | The directory containing the pom.xml file for the project.
Useful when the source of your maven project is not in the root directory of your git repo.
 |
| `cache_name` | string | maven | The cache's name prefix to allow for multiple caches and/or cache invalidation. |
| `checksum_location` | string | .maven_cache_seed | The path to save the checksum when calculating cache. |
| `command` | string | verify | The maven command(s) to run. Multiple commands can be run by providing a multi-line string. |
| `dependency_plugin_version` | string | 3.1.2 | Specify the Maven Dependency Plugin |
| `executor` | executor | default | The name of custom executor to use |
| `maven_command` | string | mvn | Specify a custom path for invoking maven |
| `mvn_step_name` | string | Run Tests | The name given to the step that runs the maven command. |
| `post_mvn_steps` | steps |  | (Optional) Steps to run immediately after maven has completed, before test results are processed. |
| `pre_mvn_steps` | steps |  | (Optional) Steps to run just before maven, after the code has been checked out and the cache has been restored. |
| `settings_file` | string |  | Specify a custom settings file to use (optional) |
| `skip_checkout` | boolean | false | Skip the checkout step if set to true. Useful when pre-steps are passed in to the job that will obtain the source code. |
| `test_results_path` | string | target/surefire-reports | The path to the test results. |
| `verify_dependencies` | boolean | true | Verify dependencies are valid and available from public sources |

## Executors

### default

CircleCI Java JDK image.
Defaults to Java 17.0 and size "small".


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | string | small | The resource class to use for the executor.
 |
| `tag` | string | 17.0 | Can be changed to any of the available tags listed on the DockerHub for this image.
https://hub.docker.com/r/cimg/openjdk/tags
 |

## Examples

### custom_command

Use parameters to run custom Maven commands. In the example below we are running maven verify with debug mode enabled.


```yaml
version: '2.1'
orbs:
  maven: circleci/maven@x.y
workflows:
  maven_test:
    jobs:
      - maven/test:
          command: '-X verify'
```

### custom_test_results_path

If your tests results are not in the default (target/surefire-reports) directory then you could add a custom directory.


```yaml
version: '2.1'
orbs:
  maven: circleci/maven@x.y
workflows:
  maven_test:
    jobs:
      - maven/test:
          test_results_path: /path/to/test/results
```

### maven_test

If you have a standard maven project, you can use this orb to run through a common maven workflow. Without any additional configuration you can build, test, and automatically have your test results uploaded to CircleCI.


```yaml
version: '2.1'
orbs:
  maven: circleci/maven@x.y
workflows:
  maven_test:
    jobs:
      - maven/test
```

### test_executor_matrix

This example shows how to use the matrix key to launch against multiple
cimg/openjdk images.


```yaml
version: '2.1'
orbs:
  maven: circleci/maven@1.1
workflows:
  maven_test:
    jobs:
      - maven/test:
          matrix:
            parameters:
              executor:
                - j13
                - j15
```

### test_with_executor

This example shows how to define an a custom executor for the maven/test job.


```yaml
version: '2.1'
orbs:
  maven: circleci/maven@1.1
workflows:
  maven_test:
    jobs:
      - maven/test:
          executor: example
```