Skip to content

Update README.md to link to Maven repository #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 17, 2024
Merged

Update README.md to link to Maven repository #12

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3831935
Update README.md to link to Maven repository
Jul 17, 2024
62f9d1b
Add maven-central icon
Jul 17, 2024
21868b5
Center the headline and maven-central icon
Jul 17, 2024
06fe3fe
Fix the maven-central logo and link
Jul 17, 2024
6120067
Add a license badge
Jul 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 28 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,21 @@
# Cover Annotations
<h1 align="center">Cover Annotations</h1>

Cover Annotations allows users to annotate their Java codebase with advice on how best to test it.
In turn this can be used by [Diffblue Cover](https://diffblue.com/cover) to tune the tests it writes.

## Installation
<div align="center">

### Maven
[![Apache 2.0](https://img.shields.io/github/license/diffblue/cover-annotations)](https://www.apache.org/licenses/LICENSE-2.0)
[![Maven Central](https://img.shields.io/maven-central/v/com.diffblue.cover/cover-annotations.svg)](https://central.sonatype.com/artifact/com.diffblue.cover/cover-annotations/overview)

In order to use the annotations in your Maven project then the Diffblue repository and `cover-annotations` dependency will need to be added into your `pom.xml`:
</div>

```xml
<dependencies>
<dependency>
<groupId>com.diffblue.cover</groupId>
<artifactId>cover-annotations</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>
```

### Gradle

In order to use the annotations in your Gradle project then the Diffblue repository and `cover-annotations` dependency will need to be added into your `build.gradle`:
Cover Annotations allows users to annotate their Java codebase with advice on how best to test it.
In turn this can be used by [Diffblue Cover](https://diffblue.com/cover) to tune the tests it writes.

```gradle
dependencies {
implementation("com.diffblue.cover:cover-annotations:1.1.0")
}
```
## Installation

Or similarly for `build.gradle.kts`:
Cover Annotations is published in the [Maven central repository](https://central.sonatype.com/artifact/com.diffblue.cover/cover-annotations/overview).
In order to use the annotations simply add `cover-annotations` as a dependency to your project, for example copying the snippet for Maven or Gradle from the repository page.

```
dependencies {
implementation("com.diffblue.cover:cover-annotations:1.1.0")
}
```
## Usage

Annotations placed on packages affect tests for all classes and methods under test in that package.
Annotations placed on classes affect tests for that class and all its methods under test, overriding package level annotations.
Expand All @@ -44,11 +24,11 @@ Annotations placed on methods affect just that method under test, overriding pac
The annotations will be respected by Diffblue Cover via both command line and IntelliJ Plugin.
When used from the command line in conjunction with equivalent options then the command line options take priority over the annotations found.

## Mocking Annotations
### Mocking Annotations

Mocking annotations allow fine grained control over what mocking should be preferred when testing.

### Using `@InTestsMock`
#### Using `@InTestsMock`

Perhaps you have a method that Diffblue Cover would ordinarily test using an `Integer` but you'd prefer to see it tested using `Mockito.mock(..)`.
In this case you could annotate the method (or class, or package) to recommend mocking `Number`:
Expand Down Expand Up @@ -80,7 +60,7 @@ public class ClassUnderTest {
> dcover create --mock ClassToMock --disable-mock-inputs ClassToForbidMocking
> ```

### Using `@InTestsMockConstruction`
#### Using `@InTestsMockConstruction`

Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using `Mockito.mockConstruction(Random.class)`.
In this case you could annotate the method (or class, or package) to recommend mocking construction of `Random`:
Expand All @@ -101,7 +81,7 @@ public class ClassUnderTest {
> dcover create --mock-construction ClassToMockConstruction
> ```

### Using `@InTestsMockStatic`
#### Using `@InTestsMockStatic`

Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using `Mockito.mockStatic(UUID.class)`.
In this case you could annotate the method (or class, or package) to recommend mocking static methods of `UUID`:
Expand All @@ -122,11 +102,11 @@ public class ClassUnderTest {
> dcover create --mock-static ClassToMockStatic
> ```

## Custom Input Annotations
### Custom Input Annotations

Custom input annotations allow particular inputs to be recommended to Diffblue Cover when writing tests.

### Using `@InTestsUseEnums`
#### Using `@InTestsUseEnums`

The `@InTestsUseEnums` annotation allows the user to recommend specific `enum` literal values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -137,7 +117,7 @@ public static boolean isDateOrTimeBased(@InTestsUseEnums({"SECONDS", "YEARS", "F
}
```

### Using `@InTestsUseClasses`
#### Using `@InTestsUseClasses`

The `@InTestsUseClasses` annotation allows the user to recommend specific `Class` literal values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -149,7 +129,7 @@ public static boolean isAnnotation(@InTestsUseClasses(Nullable.class) Class<?> t
}
```

### Using `@InTestsUseStrings`
#### Using `@InTestsUseStrings`

The `@InTestsUseStrings` annotation allows the user to recommend specific `String` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -164,7 +144,7 @@ public static boolean isDayRelatedSongTitle(@InTestsUseStrings({"I Don't Like Mo
}
```

### Using `@InTestsUseCharacters`
#### Using `@InTestsUseCharacters`

The `@InTestsUseCharacters` annotation allows the user to recommend specific `char` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -182,7 +162,7 @@ public static Integer toNullableCodePoint(
}
```

### Using `@InTestsUseBytes`
#### Using `@InTestsUseBytes`

The `@InTestsUseBytes` annotation allows the user to recommend specific `byte` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -194,7 +174,7 @@ public static String toUpperHexString(@InTestsUseBytes((byte)0xD1) byte input) {
}
```

### Using `@InTestsUseShorts`
#### Using `@InTestsUseShorts`

The `@InTestsUseShorts` annotation allows the user to recommend specific `short` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -206,7 +186,7 @@ public static String toUpperHexString(@InTestsUseShorts((short)0xD1FF) short inp
}
```

### Using `@InTestsUseIntegers`
#### Using `@InTestsUseIntegers`

The `@InTestsUseIntegers` annotation allows the user to recommend specific `int` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -218,7 +198,7 @@ public static String toUpperHexString(@InTestsUseIntegers(0xD1FFB) int input) {
}
```

### Using `@InTestsUseLongs`
#### Using `@InTestsUseLongs`

The `@InTestsUseLongs` annotation allows the user to recommend specific `long` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -230,7 +210,7 @@ public static String toUpperHexString(@InTestsUseLongs(0xD1FFBL) long input) {
}
```

### Using `@InTestsUseFloats`
#### Using `@InTestsUseFloats`

The `@InTestsUseFloats` annotation allows the user to recommend specific `float` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -242,7 +222,7 @@ public static boolean isNearPi(@InTestsUseFloats(3.14159f) float input) {
}
```

### Using `@InTestsUseDoubles`
#### Using `@InTestsUseDoubles`

The `@InTestsUseDoubles` annotation allows the user to recommend specific `double` values to use in tests.
Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
Expand All @@ -254,11 +234,11 @@ public static boolean isNearPi(@InTestsUseDoubles(Math.PI) float input) {
}
```

## Interesting Value Annotations
### Interesting Value Annotations

Interesting value annotations allow users to promote existing fields and methods to be identified and used in particular roles by Diffblue Cover when writing tests.

### Using `@InterestingTestFactory`
#### Using `@InterestingTestFactory`

Indicates the annotated method as a useful factory method for use in tests.
Cover will automatically recognise factory methods that simply return a newly created instance, but may not identify more complicated factories.
Expand Down
Loading