README.md - platform/external/TestParameterInjector - Git at Google

 TestParameterInjector
 =====================

 [Link to Javadoc.](https://google.github.io/TestParameterInjector/docs/latest/)

 ## Introduction

 `TestParameterInjector` is a JUnit4 test runner that runs its test methods for
 different combinations of field/parameter values.

 Parameterized tests are a great way to avoid code duplication between tests and
 promote high test coverage for data-driven tests.

 There are a lot of alternative parameterized test frameworks, such as
 [junit.runners.Parameterized](https://github.com/junit-team/junit4/wiki/parameterized-tests)
 and [JUnitParams](https://github.com/Pragmatists/JUnitParams). We believe
 `TestParameterInjector` is an improvement of those because it is more powerful
 and simpler to use.

 [This blogpost](https://opensource.googleblog.com/2021/03/introducing-testparameterinjector.html)
 goes into a bit more detail about how `TestParameterInjector` compares to other
 frameworks used at Google.

 ## Getting started

 To start using `TestParameterInjector` right away, copy the following snippet:

 ```java
 import com.google.testing.junit.testparameterinjector.TestParameterInjector;
 import com.google.testing.junit.testparameterinjector.TestParameter;

 @RunWith(TestParameterInjector.class)
 public class MyTest {

   @TestParameter boolean isDryRun;

   @Test public void test1(@TestParameter boolean enableFlag) {
     // ...
   }

   @Test public void test2(@TestParameter MyEnum myEnum) {
     // ...
   }

   enum MyEnum { VALUE_A, VALUE_B, VALUE_C }
 }
 ```

 And add the following dependency to your `.pom` file:

 ```xml
 <dependency>
   <groupId>com.google.testparameterinjector</groupId>
   <artifactId>test-parameter-injector</artifactId>
   <version>1.4</version>
 </dependency>
 ```

 or see [this maven.org
 page](https://search.maven.org/artifact/com.google.testparameterinjector/test-parameter-injector)
 for instructions for other build tools.


 ## Basics

 ### `@TestParameter` for testing all combinations

 #### Parameterizing a single test method

 The simplest way to use this library is to use `@TestParameter`. For example:

 ```java
 @RunWith(TestParameterInjector.class)
 public class MyTest {

   @Test
   public void test(@TestParameter boolean isOwner) {...}
 }
 ```

 In this example, two tests will be automatically generated by the test framework:

 -   One with `isOwner` set to `true`
 -   One with `isOwner` set to `false`

 When running the tests, the result will show the following test names:

 ```
 MyTest#test[isOwner=true]
 MyTest#test[isOwner=false]
 ```

 #### Parameterizing the whole class

 `@TestParameter` can also annotate a field:

 ```java
 @RunWith(TestParameterInjector.class)
 public class MyTest {

   @TestParameter private boolean isOwner;

   @Test public void test1() {...}
   @Test public void test2() {...}
 }
 ```

 In this example, both `test1` and `test2` will be run twice (once for each
 parameter value).

 #### Supported types

 The following examples show most of the supported types. See the `@TestParameter` javadoc for more details.

 ```java
 // Enums
 @TestParameter AnimalEnum a; // Implies all possible values of AnimalEnum
 @TestParameter({"CAT", "DOG"}) AnimalEnum a; // Implies AnimalEnum.CAT and AnimalEnum.DOG.

 // Strings
 @TestParameter({"cat", "dog"}) String animalName;

 // Java primitives
 @TestParameter boolean b; // Implies {true, false}
 @TestParameter({"1", "2", "3"}) int i;
 @TestParameter({"1", "1.5", "2"}) double d;

 // Bytes
 @TestParameter({"!!binary 'ZGF0YQ=='", "some_string"}) byte[] bytes;
 ```

 For non-primitive types (e.g. String, enums, bytes), `"null"` is always parsed as the `null` reference.

 #### Multiple parameters: All combinations are run

 If there are multiple `@TestParameter`-annotated values applicable to one test
 method, the test is run for all possible combinations of those values. Example:

 ```java
 @RunWith(TestParameterInjector.class)
 public class MyTest {

   @TestParameter private boolean a;

   @Test public void test1(@TestParameter boolean b, @TestParameter boolean c) {
     // Run for these combinations:
     //   (a=false, b=false, c=false)
     //   (a=false, b=false, c=true )
     //   (a=false, b=true,  c=false)
     //   (a=false, b=true,  c=true )
     //   (a=true,  b=false, c=false)
     //   (a=true,  b=false, c=true )
     //   (a=true,  b=true,  c=false)
     //   (a=true,  b=true,  c=true )
   }
 }
 ```

 If you want to explicitly define which combinations are run, see the next
 sections.

 ### Use a test enum for enumerating more complex parameter combinations

 Use this strategy if you want to:

 -   Explicitly specify the combination of parameters
 -   or your parameters are too large to be encoded in a `String` in a readable
     way

 Example:

 ```java
 @RunWith(TestParameterInjector.class)
 class MyTest {

   enum FruitVolumeTestCase {
     APPLE(Fruit.newBuilder().setName("Apple").setShape(SPHERE).build(), /* expectedVolume= */ 3.1),
     BANANA(Fruit.newBuilder().setName("Banana").setShape(CURVED).build(), /* expectedVolume= */ 2.1),
     MELON(Fruit.newBuilder().setName("Melon").setShape(SPHERE).build(), /* expectedVolume= */ 6);

     final Fruit fruit;
     final double expectedVolume;

     FruitVolumeTestCase(Fruit fruit, double expectedVolume) { ... }
   }

   @Test
   public void calculateVolume_success(@TestParameter FruitVolumeTestCase fruitVolumeTestCase) {
     assertThat(calculateVolume(fruitVolumeTestCase.fruit))
         .isEqualTo(fruitVolumeTestCase.expectedVolume);
   }
 }
 ```

 The enum constant name has the added benefit of making for sensible test names:

 ```
 MyTest#calculateVolume_success[APPLE]
 MyTest#calculateVolume_success[BANANA]
 MyTest#calculateVolume_success[MELON]
 ```

 ### `@TestParameters` for defining sets of parameters

 You can also explicitly enumerate the sets of test parameters via a list of YAML
 mappings:

 ```java
 @Test
 @TestParameters({
   "{age: 17, expectIsAdult: false}",
   "{age: 22, expectIsAdult: true}",
 })
 public void personIsAdult(int age, boolean expectIsAdult) { ... }
 ```

 The string format supports the same types as `@TestParameter` (e.g. enums). See
 the `@TestParameters` javadoc for more info.

 `@TestParameters` works in the same way on the constructor, in which case all
 tests will be run for the given parameter sets.

 ## Advanced usage

 ### Dynamic parameter generation for `@TestParameter`

 Instead of providing a list of parsable strings, you can implement your own
 `TestParameterValuesProvider` as follows:

 ```java
 @Test
 public void matchesAllOf_throwsOnNull(
     @TestParameter(valuesProvider = CharMatcherProvider.class) CharMatcher charMatcher) {
   assertThrows(NullPointerException.class, () -> charMatcher.matchesAllOf(null));
 }

 private static final class CharMatcherProvider implements TestParameterValuesProvider {
   @Override
   public List<CharMatcher> provideValues() {
     return ImmutableList.of(CharMatcher.any(), CharMatcher.ascii(), CharMatcher.whitespace());
   }
 }
 ```

 Note that `provideValues()` dynamically construct the returned list, e.g. by
 reading a file. There are no restrictions on the object types returned, but note
 that `toString()` will be used for the test names.

 ### Dynamic parameter generation for `@TestParameters`

 Instead of providing a YAML mapping of parameters, you can implement your own
 `TestParametersValuesProvider` as follows:

 ```java
 @Test
 @TestParameters(valuesProvider = IsAdultValueProvider.class)
 public void personIsAdult(int age, boolean expectIsAdult) { ... }

 static final class IsAdultValueProvider implements TestParametersValuesProvider {
   @Override public ImmutableList<TestParametersValues> provideValues() {
     return ImmutableList.of(
       TestParametersValues.builder()
         .name("teenager")
         .addParameter("age", 17)
         .addParameter("expectIsAdult", false)
         .build(),
       TestParametersValues.builder()
         .name("young adult")
         .addParameter("age", 22)
         .addParameter("expectIsAdult", true)
         .build()
     );
   }
 }
 ```
	TestParameterInjector
	=====================

	[Link to Javadoc.](https://google.github.io/TestParameterInjector/docs/latest/)

	## Introduction

	`TestParameterInjector` is a JUnit4 test runner that runs its test methods for
	different combinations of field/parameter values.

	Parameterized tests are a great way to avoid code duplication between tests and
	promote high test coverage for data-driven tests.

	There are a lot of alternative parameterized test frameworks, such as
	[junit.runners.Parameterized](https://github.com/junit-team/junit4/wiki/parameterized-tests)
	and [JUnitParams](https://github.com/Pragmatists/JUnitParams). We believe
	`TestParameterInjector` is an improvement of those because it is more powerful
	and simpler to use.

	[This blogpost](https://opensource.googleblog.com/2021/03/introducing-testparameterinjector.html)
	goes into a bit more detail about how `TestParameterInjector` compares to other
	frameworks used at Google.

	## Getting started

	To start using `TestParameterInjector` right away, copy the following snippet:

	```java
	import com.google.testing.junit.testparameterinjector.TestParameterInjector;
	import com.google.testing.junit.testparameterinjector.TestParameter;

	@RunWith(TestParameterInjector.class)
	public class MyTest {

	@TestParameter boolean isDryRun;

	@Test public void test1(@TestParameter boolean enableFlag) {
	// ...
	}

	@Test public void test2(@TestParameter MyEnum myEnum) {
	// ...
	}

	enum MyEnum { VALUE_A, VALUE_B, VALUE_C }
	}
	```

	And add the following dependency to your `.pom` file:

	```xml
	<dependency>
	<groupId>com.google.testparameterinjector</groupId>
	<artifactId>test-parameter-injector</artifactId>
	<version>1.4</version>
	</dependency>
	```

	or see [this maven.org
	page](https://search.maven.org/artifact/com.google.testparameterinjector/test-parameter-injector)
	for instructions for other build tools.


	## Basics

	### `@TestParameter` for testing all combinations

	#### Parameterizing a single test method

	The simplest way to use this library is to use `@TestParameter`. For example:

	```java
	@RunWith(TestParameterInjector.class)
	public class MyTest {

	@Test
	public void test(@TestParameter boolean isOwner) {...}
	}
	```

	In this example, two tests will be automatically generated by the test framework:

	- One with `isOwner` set to `true`
	- One with `isOwner` set to `false`

	When running the tests, the result will show the following test names:

	```
	MyTest#test[isOwner=true]
	MyTest#test[isOwner=false]
	```

	#### Parameterizing the whole class

	`@TestParameter` can also annotate a field:

	```java
	@RunWith(TestParameterInjector.class)
	public class MyTest {

	@TestParameter private boolean isOwner;

	@Test public void test1() {...}
	@Test public void test2() {...}
	}
	```

	In this example, both `test1` and `test2` will be run twice (once for each
	parameter value).

	#### Supported types

	The following examples show most of the supported types. See the `@TestParameter` javadoc for more details.

	```java
	// Enums
	@TestParameter AnimalEnum a; // Implies all possible values of AnimalEnum
	@TestParameter({"CAT", "DOG"}) AnimalEnum a; // Implies AnimalEnum.CAT and AnimalEnum.DOG.

	// Strings
	@TestParameter({"cat", "dog"}) String animalName;

	// Java primitives
	@TestParameter boolean b; // Implies {true, false}
	@TestParameter({"1", "2", "3"}) int i;
	@TestParameter({"1", "1.5", "2"}) double d;

	// Bytes
	@TestParameter({"!!binary 'ZGF0YQ=='", "some_string"}) byte[] bytes;
	```

	For non-primitive types (e.g. String, enums, bytes), `"null"` is always parsed as the `null` reference.

	#### Multiple parameters: All combinations are run

	If there are multiple `@TestParameter`-annotated values applicable to one test
	method, the test is run for all possible combinations of those values. Example:

	```java
	@RunWith(TestParameterInjector.class)
	public class MyTest {

	@TestParameter private boolean a;

	@Test public void test1(@TestParameter boolean b, @TestParameter boolean c) {
	// Run for these combinations:
	// (a=false, b=false, c=false)
	// (a=false, b=false, c=true )
	// (a=false, b=true, c=false)
	// (a=false, b=true, c=true )
	// (a=true, b=false, c=false)
	// (a=true, b=false, c=true )
	// (a=true, b=true, c=false)
	// (a=true, b=true, c=true )
	}
	}
	```

	If you want to explicitly define which combinations are run, see the next
	sections.

	### Use a test enum for enumerating more complex parameter combinations

	Use this strategy if you want to:

	- Explicitly specify the combination of parameters
	- or your parameters are too large to be encoded in a `String` in a readable
	way

	Example:

	```java
	@RunWith(TestParameterInjector.class)
	class MyTest {

	enum FruitVolumeTestCase {
	APPLE(Fruit.newBuilder().setName("Apple").setShape(SPHERE).build(), /* expectedVolume= */ 3.1),
	BANANA(Fruit.newBuilder().setName("Banana").setShape(CURVED).build(), /* expectedVolume= */ 2.1),
	MELON(Fruit.newBuilder().setName("Melon").setShape(SPHERE).build(), /* expectedVolume= */ 6);

	final Fruit fruit;
	final double expectedVolume;

	FruitVolumeTestCase(Fruit fruit, double expectedVolume) { ... }
	}

	@Test
	public void calculateVolume_success(@TestParameter FruitVolumeTestCase fruitVolumeTestCase) {
	assertThat(calculateVolume(fruitVolumeTestCase.fruit))
	.isEqualTo(fruitVolumeTestCase.expectedVolume);
	}
	}
	```

	The enum constant name has the added benefit of making for sensible test names:

	```
	MyTest#calculateVolume_success[APPLE]
	MyTest#calculateVolume_success[BANANA]
	MyTest#calculateVolume_success[MELON]
	```

	### `@TestParameters` for defining sets of parameters

	You can also explicitly enumerate the sets of test parameters via a list of YAML
	mappings:

	```java
	@Test
	@TestParameters({
	"{age: 17, expectIsAdult: false}",
	"{age: 22, expectIsAdult: true}",
	})
	public void personIsAdult(int age, boolean expectIsAdult) { ... }
	```

	The string format supports the same types as `@TestParameter` (e.g. enums). See
	the `@TestParameters` javadoc for more info.

	`@TestParameters` works in the same way on the constructor, in which case all
	tests will be run for the given parameter sets.

	## Advanced usage

	### Dynamic parameter generation for `@TestParameter`

	Instead of providing a list of parsable strings, you can implement your own
	`TestParameterValuesProvider` as follows:

	```java
	@Test
	public void matchesAllOf_throwsOnNull(
	@TestParameter(valuesProvider = CharMatcherProvider.class) CharMatcher charMatcher) {
	assertThrows(NullPointerException.class, () -> charMatcher.matchesAllOf(null));
	}

	private static final class CharMatcherProvider implements TestParameterValuesProvider {
	@Override
	public List<CharMatcher> provideValues() {
	return ImmutableList.of(CharMatcher.any(), CharMatcher.ascii(), CharMatcher.whitespace());
	}
	}
	```

	Note that `provideValues()` dynamically construct the returned list, e.g. by
	reading a file. There are no restrictions on the object types returned, but note
	that `toString()` will be used for the test names.

	### Dynamic parameter generation for `@TestParameters`

	Instead of providing a YAML mapping of parameters, you can implement your own
	`TestParametersValuesProvider` as follows:

	```java
	@Test
	@TestParameters(valuesProvider = IsAdultValueProvider.class)
	public void personIsAdult(int age, boolean expectIsAdult) { ... }

	static final class IsAdultValueProvider implements TestParametersValuesProvider {
	@Override public ImmutableList<TestParametersValues> provideValues() {
	return ImmutableList.of(
	TestParametersValues.builder()
	.name("teenager")
	.addParameter("age", 17)
	.addParameter("expectIsAdult", false)
	.build(),
	TestParametersValues.builder()
	.name("young adult")
	.addParameter("age", 22)
	.addParameter("expectIsAdult", true)
	.build()
	);
	}
	}
	```