mongoUnit

https://mongounit.org
Admin
mongoUnit is a JUnit 5 extension and data-driven integration testing framework for Spring Boot...
Tokens:44,894
Snippets:480
Trust Score:5.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Seeding JSON Format Example

Source: https://mongounit.org/json-format.html

This JSON structure defines collections and documents for seeding a database. It includes examples of how to specify OBJECT_ID and DATE_TIME BSON types.

```json
[
{
  "collectionName": "people",
  "documents": [
  {
    "_id": { "$$OBJECT_ID": "5db7545b7b615c739732c777" },
    "name": "Bob The Builder",
    "created": {     
      "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
    }
  }
  ]
},
{
  "collectionName": "positions",
  "documents": [
    {
      "positionName": "Builder",
      "_id": {
        "$$OBJECT_ID": "5db7545b7b615c739732c776"
      },
      "created": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      },
      "updated": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      }
    }
  ]
}
]

```

--------------------------------

### Example Assertion JSON Structure

Source: https://mongounit.org/json-format.html

This is a comprehensive example of an assertion JSON file, demonstrating the structure for multiple collections and documents, including special syntax for Object IDs and Date Times.

```json
[
{
  "collectionName": "positions",
  "documents": [
    {
      "_id": {
        "$$OBJECT_ID": "5db7545b7b615c739732c776"
      },
      "positionName": "Builder",
      "created": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      },
      "updated": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      }
    }
  ]
},
{
  "collectionName": "people",
  "documents": [
    {
      "_id": {
        "$$OBJECT_ID": "5db7545b7b615c739732c777"
      },
      "positionId": "5db7545b7b615c739732c776",
      "name": "Bob The Builder",
      "favColors": [
        "red",
        "green"
      ],
      "address": {
        "zipcode": 12345,
        "street": "12 Builder St."
      },
      "created": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      },
      "updated": {
        "$$DATE_TIME": "2019-10-28T16:49:31.442Z"
      }
    },
    {
      "name": "Robert",
      "positionId": "5db7545b7b615c739732c776",
      "favColors": [
        "blue",
        "white"
      ],
      "address": {
        "zipcode": 12345,
        "street": "13 Builder St."
      },
      "created": {
        "$$DATE_TIME": "2019-10-28T17:05:36.132Z",
        "comparator": "<"
      },
      "updated": {
        "$$DATE_TIME": "2019-10-28T17:05:36.132Z",
        "comparator": "<"
      }
    }
  ]
}
]
```

--------------------------------

### getOutputPath

Source: https://mongounit.org/javadoc/index-all.html

Gets the output path.

```APIDOC
## getOutputPath()

### Description
Gets the output path.

### Method
Method

### Class
org.mongounit.DatasetGeneratorArguments
```

--------------------------------

### getObject

Source: https://mongounit.org/javadoc/index-all.html

Gets the object.

```APIDOC
## getObject()

### Description
Gets the object.

### Method
Method

### Class
org.mongounit.config.MongoDatabaseFactoryBean
```

--------------------------------

### getMongoClientURI

Source: https://mongounit.org/javadoc/index-all.html

Gets the MongoClientURI.

```APIDOC
## getMongoClientURI()

### Description
Gets the MongoClientURI.

### Method
Method

### Class
org.mongounit.DatasetGeneratorArguments
```

--------------------------------

### MongoUnitExtension Methods

Source: https://mongounit.org/javadoc/index-all.html

Methods provided by the MongoUnitExtension for managing test setup.

```APIDOC
## beforeAll(ExtensionContext)

Method in class org.mongounit.MongoUnitExtension
```

```APIDOC
## beforeEach(ExtensionContext)

Method in class org.mongounit.MongoUnitExtension
```

--------------------------------

### getValue

Source: https://mongounit.org/javadoc/index-all.html

Gets the value.

```APIDOC
## getValue()

### Description
Gets the value.

### Method
Method

### Class
org.mongounit.model.MongoUnitValue
```

--------------------------------

### getDocuments

Source: https://mongounit.org/javadoc/index-all.html

Gets the documents.

```APIDOC
## getDocuments()

### Description
Gets the documents.

### Method
Method

### Class
org.mongounit.model.MongoUnitCollection
```

--------------------------------

### getBaseUri

Source: https://mongounit.org/javadoc/index-all.html

Gets the base URI.

```APIDOC
## getBaseUri()

### Description
Gets the base URI.

### Method
Method

### Class
org.mongounit.config.MongoUnitProperties
```

--------------------------------

### ApplicationLifecycle Methods

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfiguration.ApplicationLifecycle.html

This component implements the Spring Lifecycle interface, providing methods to start, stop, and check the running status of the application context related to MongoUnit.

```APIDOC
## ApplicationLifecycle

This class is a Spring component used to optionally drop the database once all the tests complete execution.

### Methods

#### `start()`

- **Description**: Starts the lifecycle of the component. This method is part of the `org.springframework.context.Lifecycle` interface.
- **Method**: `void start()`

#### `stop()`

- **Description**: Stops the lifecycle of the component. This method is part of the `org.springframework.context.Lifecycle` interface.
- **Method**: `void stop()`

#### `isRunning()`

- **Description**: Checks if the component is currently running. This method is part of the `org.springframework.context.Lifecycle` interface.
- **Method**: `boolean isRunning()`
- **Returns**: `true` if the component is running, `false` otherwise.
```

--------------------------------

### getBsonType

Source: https://mongounit.org/javadoc/index-all.html

Gets the BSON type.

```APIDOC
## getBsonType()

### Description
Gets the BSON type.

### Method
Method

### Class
org.mongounit.model.MongoUnitValue
```

--------------------------------

### Generate JSON Snapshot with Database URI

Source: https://mongounit.org/getting-started.html

Use this command to generate a JSON snapshot of your database by specifying the full database URI. The output will be written to output.json.

```bash
$ java -jar mongounit-3.1.2-jar-with-dependencies.jar -dbUri=mongodb://localhost:27017/yourDbName

**************************
**** JSON was written to /.../output.json
**************************
$ 

```

--------------------------------

### MongoUnitProperties Methods

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitProperties.html

Details the instance methods available for retrieving configuration values from a MongoUnitProperties object.

```APIDOC
## getBaseUri()

### Description
Retrieves the base URI configuration.

### Method
`String getBaseUri()`
```

```APIDOC
## getMongoUnitValueFieldNameIndicator()

### Description
Returns the field name to use as an indicator in developer JSON files to signify that a document is a representation of a special MongoUnit value.

### Method
`String getMongoUnitValueFieldNameIndicator()`
```

```APIDOC
## getTimeZoneId()

### Description
Retrieves the time zone ID configuration.

### Method
`String getTimeZoneId()`
```

```APIDOC
## isBaseUriKeepAsIs()

### Description
Checks if the base URI should be kept as is.

### Method
`boolean isBaseUriKeepAsIs()`
```

```APIDOC
## isDropDatabase()

### Description
Checks if the test database should be dropped.

### Method
`boolean isDropDatabase()`
```

```APIDOC
## toString()

### Description
Returns a string representation of the MongoUnitProperties object.

### Method
`String toString()`
```

--------------------------------

### MongoUnitProperties Constructors

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitProperties.html

Provides details on how to instantiate the MongoUnitProperties class.

```APIDOC
## MongoUnitProperties()

### Description
Default constructor for MongoUnitProperties.

### Constructor
`MongoUnitProperties()`
```

```APIDOC
## MongoUnitProperties(String baseUri, Boolean baseUriKeepAsIs, String mongoUnitValueFieldNameIndicator, Boolean dropDatabase, String timeZoneId)

### Description
Constructor for MongoUnitProperties with specified configuration values.

### Constructor
`MongoUnitProperties(String baseUri, Boolean baseUriKeepAsIs, String mongoUnitValueFieldNameIndicator, Boolean dropDatabase, String timeZoneId)`
```

--------------------------------

### MongoUnitConfiguration Static Method

Source: https://mongounit.org/javadoc/index-all.html

Method for creating database guard configurations.

```APIDOC
## createDatabaseGuardConfiguration()

Static method in class org.mongounit.config.MongoUnitConfiguration
```

--------------------------------

### MongoUnitProperties Constructors

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitProperties.html

Constructors for initializing MongoUnitProperties.

```APIDOC
## Constructor Details

### MongoUnitProperties
public MongoUnitProperties()
Default constructor.

### MongoUnitProperties
public MongoUnitProperties(String baseUri, Boolean baseUriKeepAsIs, String mongoUnitValueFieldNameIndicator, Boolean dropDatabase, String timeZoneId)
Constructor. NOTE: Passing 'null' to any of the arguments sets those arguments to their default value.

Parameters:
    `baseUri` - Base URI to base the dynamic database name on.
    `baseUriKeepAsIs` - Flag to indicate that the base URI should be used for testing as is, without appending anything to it.
    `mongoUnitValueFieldNameIndicator` - Field name to use as an indicator in developer JSON files to signify that a document is a representation of a special MongoUnit BSON value that specifies BSON value type based on the naming in `BsonType` enum.
    `dropDatabase` - Flag to indicate if the test database should be dropped after all the tests have run.
    `timeZoneId` - Time zone ID to use in the database name pad.
```

--------------------------------

### Seed and Assert Data with Annotations

Source: https://mongounit.org/getting-started.html

Use @SeedWithDataset to populate the database with initial data from a JSON file before a test runs, and @AssertMatchesDataset to verify the database state against expected data in another JSON file after the test. The file paths are derived from the test class and method names.

```java
@Test
@DisplayName("Create person on a non-empty database")
@SeedWithDataset
@AssertMatchesDataset
void createPersonWithExistingData() {

  CreatePersonRequest request = CreatePersonRequest.builder()
      .name("Robert")
      .address(Address.builder().street("13 Builder St.").zipcode(12345).build())
      .favColors(Arrays.asList("blue", "white"))
      .positionName("Builder")
      .build();

  mongoPersonDaoService.createPerson(request);
}
```

--------------------------------

### main Method

Source: https://mongounit.org/javadoc/org/mongounit/DatasetGenerator.html

The main method for the DatasetGenerator, serving as the entry point for the standalone program.

```APIDOC
## main(String[] args)

### Description
Main method for the DatasetGenerator. This is the entry point for the standalone program used to generate dataset files.

### Method
static void main(String[] args)

### Parameters
#### Path Parameters
- **args** (String[]) - Arguments that are passed into the standalone program.
```

--------------------------------

### getObjectType

Source: https://mongounit.org/javadoc/index-all.html

Gets the object type.

```APIDOC
## getObjectType()

### Description
Gets the object type.

### Method
Method

### Class
org.mongounit.config.MongoDatabaseFactoryBean
```

--------------------------------

### getMessage

Source: https://mongounit.org/javadoc/index-all.html

Gets the assertion message.

```APIDOC
## getMessage()

### Description
Gets the assertion message.

### Method
Method

### Class
org.mongounit.model.AssertionResult
```

--------------------------------

### MongoUnitProperties(String, Boolean, String, Boolean, String)

Source: https://mongounit.org/javadoc/index-all.html

Constructor for the MongoUnitProperties class with specified parameters.

```APIDOC
## MongoUnitProperties(String, Boolean, String, Boolean, String)

### Description
Constructor for the `MongoUnitProperties` class.

### Method
Constructor
```

--------------------------------

### getComparatorValue

Source: https://mongounit.org/javadoc/index-all.html

Gets the comparator value.

```APIDOC
## getComparatorValue()

### Description
Gets the comparator value.

### Method
Method

### Class
org.mongounit.model.MongoUnitValue
```

--------------------------------

### getCollectionNames

Source: https://mongounit.org/javadoc/index-all.html

Gets the collection names.

```APIDOC
## getCollectionNames()

### Description
Gets the collection names.

### Method
Method

### Class
org.mongounit.DatasetGeneratorArguments
```

--------------------------------

### Display dataset generator usage and options

Source: https://mongounit.org/dataset-generator-utility.html

Running the dataset generator without arguments will display an error and list all available options, including required and optional arguments like dbUri, dbName, output, collectionNames, preserveBsonTypes, and mongoUnitValueFieldNameIndicator.

```bash
java -jar mongounit-3.1.2-jar-with-dependencies.jar 
**** ERROR: -dbUri must be specified.
**************************
* Usage: 
* java -jar mongounit-x.x.x-jar-with-dependencies.jar .jar -dbUri=mongodb://localhost:27017/test_db -collectionNames=col1,col2 -output=./output.json
* 
* Individual arguments must not have any spaces between '=' and argument value or even in the argument value itself.
* '-dbUri' (required unless '-dbName' is provided) must be a valid MongoDB URI (must include db name). Must start with 'mongodb'. Can contain username/password.
* '-dbName' (required unless '-dbUri' is provided) must be a valid MongoDB DB name. Assumes base URI to be 'mongodb://localhost:27017/'.
* '-output' (optional) is an absolute or relative path to the file that should be created with the dataset output in JSON format. An existing file with the same name will be erased. If '-output' is specified, it MUST end with '.json'. Defaults to './output.json' if '-output' is omitted.
* '-collectionNames' (optional) comma separated list of collection to limit dataset generation to. No spaces allowed between collection names. Defaults to all collections in the database.
* '-preserveBsonTypes' (optional) comma separated list of BSON types to generate explicit MongoUnit BSON type specification for. The string types are enum names from the org.bson.BsonType. If not specified, defaults to OBJECT_ID and DATE_TIME.
* '-mongoUnitValueFieldNameIndicator' (optional) field name to use in developer JSON files to signify that a document is a representation of a special MongoUnit value. If not specified, defaults to $$.
**************************


```

--------------------------------

### Generate JSON Snapshot with Database Name

Source: https://mongounit.org/getting-started.html

If your database is running locally, you can simplify the command by only specifying the database name. The utility will assume the base URI is mongodb://localhost:27017/. The output will be written to output.json.

```bash
$ java -jar mongounit-3.1.2-jar-with-dependencies.jar -dbName=yourDbName

**************************
**** JSON was written to /.../output.json
**************************


```

--------------------------------

### getCollectionName

Source: https://mongounit.org/javadoc/index-all.html

Gets the collection name.

```APIDOC
## getCollectionName()

### Description
Gets the collection name.

### Method
Method

### Class
org.mongounit.model.MongoUnitCollection
```

--------------------------------

### MongoDatabaseFactoryBean Methods

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoDatabaseFactoryBean.html

Details of the instance methods available in MongoDatabaseFactoryBean.

```APIDOC
## getObject

### Description
Returns the MongoDatabaseFactory object managed by this factory.

### Method
public org.springframework.data.mongodb.MongoDatabaseFactory getObject()

### Implements
`org.springframework.beans.factory.FactoryBean<org.springframework.data.mongodb.MongoDatabaseFactory>`
```

```APIDOC
## getObjectType

### Description
Returns the type of object that this factory produces.

### Method
public Class<?> getObjectType()

### Implements
`org.springframework.beans.factory.FactoryBean<org.springframework.data.mongodb.MongoDatabaseFactory>`
```

```APIDOC
## isSingleton

### Description
Indicates whether the bean produced by this factory is a singleton.

### Method
public boolean isSingleton()

### Implements
`org.springframework.beans.factory.FactoryBean<org.springframework.data.mongodb.MongoDatabaseFactory>`
```

```APIDOC
## afterPropertiesSet

### Description
Callback interface to be executed after all properties have been set.

### Method
public void afterPropertiesSet()

### Implements
`org.springframework.beans.factory.InitializingBean`
```

```APIDOC
## setEnvironment

### Description
Set the `Environment` that this object runs in.

### Method
public void setEnvironment(org.springframework.core.env.Environment environment)

### Implements
`org.springframework.context.EnvironmentAware`
```

--------------------------------

### DatasetGeneratorArguments Constructors

Source: https://mongounit.org/javadoc/org/mongounit/DatasetGeneratorArguments.html

Provides details on how to instantiate DatasetGeneratorArguments, including a default constructor and a comprehensive constructor with various configuration parameters.

```APIDOC
## Constructor Details

### DatasetGeneratorArguments()
Default constructor.

### DatasetGeneratorArguments(com.mongodb.MongoClientURI mongoClientURI, List<String> collectionNames, String outputPath, List<String> preserveBsonTypes, String mongoUnitValueFieldNameIndicator)
Constructor.

Parameters:
`mongoClientURI` - Validated URI of the mongo DB to connect to.
`collectionNames` - Optional list of collection names to generate data based on.
`outputPath` - Absolute path to file where to output JSON.
`preserveBsonTypes` - List of BSON types to generate explicit MongoUnit BSON type specification. The specification is based on the names (not values) of the `BsonType` enum.
`mongoUnitValueFieldNameIndicator` - Field name to use as an indicator in developer JSON files to signify that a document is a representation of a special MongoUnit value. The general format of the special name/value pair is "$$BSON_TYPE": value If the JSON is meant to seed the database, 'BSON_TYPE' is to specify a BSON type value based on the naming in `BsonType`. If the JSON is meant to assert the expected result state, the format is allowed to be simply: "$$ ": value. In addition, a 'comparator' field is expected as a sibling field name.
```

--------------------------------

### getTimeZoneId

Source: https://mongounit.org/javadoc/index-all.html

Gets the time zone ID.

```APIDOC
## getTimeZoneId()

### Description
Gets the time zone ID.

### Method
Method

### Class
org.mongounit.config.MongoUnitProperties
```

--------------------------------

### MongoUnitProperties()

Source: https://mongounit.org/javadoc/index-all.html

Default constructor for the MongoUnitProperties class.

```APIDOC
## MongoUnitProperties()

### Description
Default constructor for the `MongoUnitProperties` class.

### Method
Constructor
```

--------------------------------

### getTestClassNamePath

Source: https://mongounit.org/javadoc/index-all.html

Gets the test class name path.

```APIDOC
## getTestClassNamePath(Class<?>)

### Description
Gets the test class name path.

### Method
Static method

### Class
org.mongounit.MongoUnitUtil
```

--------------------------------

### getPreserveBsonTypes

Source: https://mongounit.org/javadoc/index-all.html

Gets whether to preserve BSON types.

```APIDOC
## getPreserveBsonTypes()

### Description
Gets whether to preserve BSON types.

### Method
Method

### Class
org.mongounit.DatasetGeneratorArguments
```

--------------------------------

### Simplified Assertion Syntax

Source: https://mongounit.org/json-format.html

Demonstrates equivalent assertion formats. The `$$` prefix can be used for any BSON type, and comparators can be omitted if the default '=' is sufficient.

```json
"name": {
  "$$STRING": "Bob",
   "comparator": "="
}
```

```json
"name": {
  "$$": "Bob",
   "comparator": "="
}
```

```json
"name": {
  "$$": "Bob"
}
```

```json
"name": "Bob"
```

--------------------------------

### loadMongoUnitProperties

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfigurationUtil.html

Loads and returns the MongoUnitProperties from the configuration file.

```APIDOC
## loadMongoUnitProperties

### Description
Loads and returns the `MongoUnitProperties` from the configuration file.

### Method
```java
public static MongoUnitProperties loadMongoUnitProperties()
```

### Returns
- `MongoUnitProperties` - Loaded MongoUnitProperties.
```

--------------------------------

### getMongoUnitValueFieldNameIndicator

Source: https://mongounit.org/javadoc/index-all.html

Gets the field name indicator for MongoUnit values.

```APIDOC
## getMongoUnitValueFieldNameIndicator()

### Description
Returns field name to use as an indicator in developer JSON files to signify that a document is a representation of a special MongoUnit value.

### Method
Method

### Class
org.mongounit.config.MongoUnitProperties
```

```APIDOC
## getMongoUnitValueFieldNameIndicator()

### Description
Gets the field name indicator for MongoUnit values.

### Method
Method

### Class
org.mongounit.DatasetGeneratorArguments
```

--------------------------------

### getTestClassNamePath

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnitUtil.html

Gets the file path for a test class name.

```APIDOC
## getTestClassNamePath

### Description
Gets the file path for a test class name.

### Method Signature
`static String getTestClassNamePath(Class<?> packagedClass)`
```

--------------------------------

### Generate JSON dataset with dbUri

Source: https://mongounit.org/dataset-generator-utility.html

Run the dataset generator utility using the -dbUri argument to specify the MongoDB connection string. The output JSON will be written to /.../output.json.

```bash
java -jar mongounit-3.1.2-jar-with-dependencies.jar -dbUri=mongodb://localhost:27017/yourDbName

**************************
**** JSON was written to /.../output.json
**************************
$
```

--------------------------------

### MongoUnitAnnotations Constructors

Source: https://mongounit.org/javadoc/org/mongounit/model/MongoUnitAnnotations.html

Provides constructors for initializing MongoUnitAnnotations, including a default constructor and one that accepts lists of dataset annotations.

```APIDOC
## Constructor Summary

### `MongoUnitAnnotations()`
Default constructor.

### `MongoUnitAnnotations(List<SeedWithDataset> seedWithDatasetAnnotations, List<AssertMatchesDataset> assertMatchesDatasetAnnotations)`
Constructor. Initializes both lists to avoid NPE when adding new items.

Parameters:
* `seedWithDatasetAnnotations` - List of `SeedWithDataset` annotations discovered on a test class or method.
* `assertMatchesDatasetAnnotations` - List of `AssertMatchesDataset` annotations discovered on a test class or method.
```

--------------------------------

### Create Database Guard Configuration

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfiguration.html

Creates a BeanDefinitionRegistryPostProcessor to protect the configured database from being wiped out by MongoUnit and test method execution. This method is annotated with @Bean, indicating it produces a Spring bean.

```java
@Bean
public static MongoDatabaseGuardConfiguration createDatabaseGuardConfiguration()
```

--------------------------------

### Annotate Test Class with @MongoUnitTest

Source: https://mongounit.org/getting-started.html

Use the @MongoUnitTest annotation on your test class to enable automatic database setup and teardown for each test. By default, it creates a unique, time-stamped database and drops all collections before each test.

```java
@SpringBootTest
@MongoUnitTest
@DisplayName("MongoPersonDaoService with MongoUnit testing framework")
public class MongoPersonDaoServiceIT {

  @Autowired
  private MongoPersonDaoService mongoPersonDaoService;
  ...
  ...

}
```

--------------------------------

### seedWithDataset (single location, Class)

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnit.html

Seeds the database with a JSON dataset from a specified location using a test class for relative pathing.

```APIDOC
## seedWithDataset(String location, Class<?> testClass)

### Description
Seeds the database with the JSON-based datasets pointed to by the provided 'locations' path array. Returns a list of `MongoUnitCollection`s that can optionally be reused for assertions in the 'assertMatches*' methods.

### Method
`public static List<MongoUnitCollection> seedWithDataset(String location, Class<?> testClass)`

### Parameters
#### Path Parameters
- `location` (String) - Path to the file containing a dataset. The location type is 'CLASS'. See javadoc org.mongounit.LocationType#CLASS for more detail.
- `testClass` (Class<?>) - Class instance of the test class.

### Returns
List of `MongoUnitCollection`s based on the data pointed to by provided 'location' and 'testClass'.
```

--------------------------------

### DatasetGenerator Constructor

Source: https://mongounit.org/javadoc/org/mongounit/DatasetGenerator.html

Initializes a new instance of the DatasetGenerator class.

```APIDOC
## DatasetGenerator()

### Description
Initializes a new instance of the DatasetGenerator class.

### Constructor
DatasetGenerator()
```

--------------------------------

### Builder Methods

Source: https://mongounit.org/javadoc/index-all.html

Static methods to obtain builders for various model and argument classes.

```APIDOC
## build()

Method in class org.mongounit.DatasetGeneratorArguments.DatasetGeneratorArgumentsBuilder
```

```APIDOC
## build()

Method in class org.mongounit.model.AssertionResult.AssertionResultBuilder
```

```APIDOC
## build()

Method in class org.mongounit.model.MongoUnitCollection.MongoUnitCollectionBuilder
```

```APIDOC
## builder()

Static method in class org.mongounit.DatasetGeneratorArguments
```

```APIDOC
## builder()

Static method in class org.mongounit.model.AssertionResult
```

```APIDOC
## builder()

Static method in class org.mongounit.model.MongoUnitCollection
```

```APIDOC
## builder()

Static method in class org.mongounit.model.MongoUnitValue
```

--------------------------------

### MongoUnitValue Constructors

Source: https://mongounit.org/javadoc/org/mongounit/model/MongoUnitValue.html

Provides details on how to instantiate the MongoUnitValue class.

```APIDOC
## MongoUnitValue()

### Description
Default constructor for the MongoUnitValue class.

### Constructor
`MongoUnitValue()`
```

```APIDOC
## MongoUnitValue(String bsonType, Object value, String comparatorValue)

### Description
Constructor for the MongoUnitValue class with specified BSON type, value, and comparator value.

### Parameters
* **bsonType** (String) - BsonType of the MongoUnit value.
* **value** (Object) - Actual value.
* **comparatorValue** (String) - Comparator value of the MongoUnit value.

### Constructor
`MongoUnitValue(String bsonType, Object value, String comparatorValue)`
```

--------------------------------

### seedWithDataset (multiple locations, Class)

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnit.html

Seeds the database with JSON datasets from specified locations using a test class for relative pathing.

```APIDOC
## seedWithDataset(String[] locations, Class<?> testClass)

### Description
Seeds the database with the JSON-based datasets pointed to by the provided 'locations' path array. Returns a list of `MongoUnitCollection`s that can optionally be reused for assertions in the 'assertMatches*' methods.

### Method
`public static List<MongoUnitCollection> seedWithDataset(String[] locations, Class<?> testClass)`

### Parameters
#### Path Parameters
- `locations` (String[]) - Array of paths to the files containing datasets. The locations type is 'CLASS'. See javadoc org.mongounit.LocationType#CLASS for more detail.
- `testClass` (Class<?>) - Class instance of the test class.

### Returns
List of `MongoUnitCollection`s based on the data pointed to by provided 'locations' and 'testClass'.
```

--------------------------------

### MongoUnitDatasets Constructors

Source: https://mongounit.org/javadoc/org/mongounit/model/MongoUnitDatasets.html

Provides constructors for initializing MongoUnitDatasets.

```APIDOC
## MongoUnitDatasets()

### Description
Default constructor.

### Method
public MongoUnitDatasets()

### Endpoint
N/A (Constructor)
```

```APIDOC
## MongoUnitDatasets(List<MongoUnitCollection> seedWithDatasets, List<MongoUnitCollection> assertMatchesDatasets, boolean assertAnnotationPresent)

### Description
Constructor to initialize with seed datasets, assert datasets, and an assertion flag.

### Method
public MongoUnitDatasets(List<MongoUnitCollection> seedWithDatasets, List<MongoUnitCollection> assertMatchesDatasets, boolean assertAnnotationPresent)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
* **seedWithDatasets** (List<MongoUnitCollection>) - Datasets to seed the database with.
* **assertMatchesDatasets** (List<MongoUnitCollection>) - Datasets to verify matching with.
* **assertAnnotationPresent** (boolean) - Flag to indicate if `AssertMatchesDataset` annotation has been encountered.
```

--------------------------------

### MongoUnit Constructor

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnit.html

Initializes a new instance of the MongoUnit class.

```APIDOC
## MongoUnit()

### Description
Initializes a new instance of the MongoUnit class.

### Constructor
`public MongoUnit()`
```

--------------------------------

### DatasetGeneratorArguments Constructors

Source: https://mongounit.org/javadoc/org/mongounit/DatasetGeneratorArguments.html

Provides constructors for initializing DatasetGeneratorArguments.

```APIDOC
## Constructors

### `DatasetGeneratorArguments()`

Default constructor.

### `DatasetGeneratorArguments(com.mongodb.MongoClientURI mongoClientURI, List<String> collectionNames, String outputPath, List<String> preserveBsonTypes, String mongoUnitValueFieldNameIndicator)`

Constructor that initializes the arguments with provided values.
```

--------------------------------

### MongoUnitUtil Static Methods

Source: https://mongounit.org/javadoc/index-all.html

Utility methods for combining datasets and comparing values.

```APIDOC
## combineDatasets(List<MongoUnitCollection>, List<MongoUnitCollection>)

Static method in class org.mongounit.MongoUnitUtil
```

```APIDOC
## combineNoRepeatingCollections(List<MongoUnitCollection>)

Static method in class org.mongounit.MongoUnitUtil
```

```APIDOC
## compare(Comparable, Comparable)

Static method in class org.mongounit.MongoUnitUtil
```

--------------------------------

### generateNewMongoClientURI (Environment)

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfigurationUtil.html

Generates a new MongoClientURI instance based on the provided Spring Environment, utilizing properties from 'mongounit.properties'.

```APIDOC
## generateNewMongoClientURI

### Description
Returns new `MongoClientURI` instance that contains newly generated URI, based on 'mongounit.properties'.

### Method
```java
public static com.mongodb.MongoClientURI generateNewMongoClientURI(org.springframework.core.env.Environment environment)
```

### Parameters
#### Path Parameters
- **environment** (org.springframework.core.env.Environment) - Required - Spring environment to look up existing properties already set, if needed.

### Returns
- `com.mongodb.MongoClientURI` - New `MongoClientURI` instance that contains newly generated URI, based on mongounit.properties.
```

--------------------------------

### Generate JSON dataset with dbName

Source: https://mongounit.org/dataset-generator-utility.html

If running your database locally, you can use the -dbName argument instead of -dbUri. The utility will assume the base URI is mongodb://localhost:27017/. The output JSON will be written to /.../output.json.

```bash
java -jar mongounit-3.1.2-jar-with-dependencies.jar -dbName=yourDbName

**************************
**** JSON was written to /.../output.json
**************************


```

--------------------------------

### Assert Dataset Matches Expected State

Source: https://mongounit.org/

Use this to assert that the current state of the database matches a predefined dataset. Ensure the dataset file exists and is correctly formatted.

```java
MongoUnit.assertMatchesDataset("updatePerson-expected.json", this.getClass());
```

--------------------------------

### compare

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnitUtil.html

Compares two comparable objects.

```APIDOC
## compare

### Description
Compares two comparable objects.

### Method Signature
`static int compare(Comparable expected, Comparable actual)`
```

--------------------------------

### MongoDatabaseFactoryBean Constructor

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoDatabaseFactoryBean.html

The default constructor for MongoDatabaseFactoryBean.

```APIDOC
## MongoDatabaseFactoryBean()

### Description
Default constructor for the MongoDatabaseFactoryBean.

### Constructor
public MongoDatabaseFactoryBean()
```

--------------------------------

### MongoUnitCollectionBuilder Methods

Source: https://mongounit.org/javadoc/org/mongounit/model/MongoUnitCollection.MongoUnitCollectionBuilder.html

This section outlines the methods used to configure a MongoUnitCollection before building it.

```APIDOC
## collectionName

### Description
Sets the name of the collection.

### Method Signature
`public MongoUnitCollection.MongoUnitCollectionBuilder collectionName(String collectionName)`

### Parameters
* **collectionName** (String) - Required - The name of the collection.

### Returns
Instance of this builder class.
```

```APIDOC
## documents

### Description
Sets the list of documents for the collection.

### Method Signature
`public MongoUnitCollection.MongoUnitCollectionBuilder documents(List<Map<String,Object>> documents)`

### Parameters
* **documents** (List<Map<String,Object>>) - Required - A list of maps, where each map represents a document with field-value pairs.

### Returns
Instance of this builder class.
```

```APIDOC
## build

### Description
Constructs and returns a new MongoUnitCollection instance with the configured properties.

### Method Signature
`public MongoUnitCollection build()`

### Returns
A new instance of the `MongoUnitCollection` class.
```

--------------------------------

### MongoUnitUtil()

Source: https://mongounit.org/javadoc/index-all.html

Constructor for the MongoUnitUtil class.

```APIDOC
## MongoUnitUtil()

### Description
Constructor for the `MongoUnitUtil` class.

### Method
Constructor
```

--------------------------------

### AssertionResult Constructors

Source: https://mongounit.org/javadoc/org/mongounit/model/AssertionResult.html

Provides details on how to instantiate an AssertionResult object.

```APIDOC
## AssertionResult()

### Description
Default constructor for creating an AssertionResult.

### Constructor
`AssertionResult()`
```

```APIDOC
## AssertionResult(boolean match, String message)

### Description
Constructor for creating an AssertionResult with match status and a message.

### Constructor
`AssertionResult(boolean match, String message)`

### Parameters
* **match** (boolean) - Required - Flag to indicate if the match was found or not.
* **message** (String) - Optional - Optional message, which is usually used as an assertion failure message to give more details.
```

--------------------------------

### generateNewMongoClientURI (String, boolean, String)

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfigurationUtil.html

Generates a new MongoClientURI instance with a base URI, an option to keep it as is, and a time zone ID.

```APIDOC
## generateNewMongoClientURI

### Description
Generates a new `MongoClientURI` instance based on the provided base URI, with options to modify the database name and specify a time zone.

### Method
```java
public static com.mongodb.MongoClientURI generateNewMongoClientURI(String baseUri, boolean baseUriKeepAsIs, String timeZoneId) throws MongoUnitException
```

### Parameters
#### Path Parameters
- **baseUri** (String) - Required - URI that works as is, but its database name is potentially added to, depending on the 'baseUriKeepAsIs' argument. Can not be 'null'.
- **baseUriKeepAsIs** (boolean) - Required - Flag to indicate if additional things should be appended to the database name, i.e., the username of the user executing the program and a one-time hash.
- **timeZoneId** (String) - Required - Time zone ID to use in the database name pad.

### Returns
- `com.mongodb.MongoClientURI` - `MongoClientURI` which is based on the provided 'baseUri'. If 'baseUriKeepAsIs' is false, the username of the user executing the program and a one-time hash is appended to the end of the database name.

### Throws
- `MongoUnitException` - If the provided 'baseUri' is not properly formatted such that its database name is not properly configured or the provided 'timeZoneId' can't be parsed.
```

--------------------------------

### Create Person Test with MongoUnit

Source: https://mongounit.org/

Tests the creation of a person in an empty database using MongoUnit. Requires no explicit seeding.

```java
package org.mongounit.demo.dao.mongo; 

import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.Arrays;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.mongounit.AssertMatchesDataset;
import org.mongounit.LocationType;
import org.mongounit.MongoUnit;
import org.mongounit.MongoUnitTest;
import org.mongounit.SeedWithDataset;
import org.mongounit.demo.dao.model.Address;
import org.mongounit.demo.dao.model.CreatePersonRequest;
import org.mongounit.demo.dao.model.Person;
import org.mongounit.demo.dao.model.UpdatePersonRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
@MongoUnitTest(name = "personDaoService")
@DisplayName("MongoPersonDaoService with MongoUnit testing framework")
public class MongoPersonDaoServiceIT {

  @Autowired
  private MongoPersonDaoService mongoPersonDaoService;

  @Test
  @DisplayName("Create person on an empty database")
  @AssertMatchesDataset
  void createPerson() {

    CreatePersonRequest request = CreatePersonRequest.builder()
        .name("Bob The Builder")
        .address(Address.builder().street("12 Builder St.").zipcode(12345).build())
        .favColors(Arrays.asList("red", "green"))
        .positionName("Builder")
        .build();

    mongoPersonDaoService.createPerson(request);
  }

  @Test
  @DisplayName("Create person on a non-empty database")
  @SeedWithDataset
  @AssertMatchesDataset
  void createPersonWithExistingData() {

    CreatePersonRequest request = CreatePersonRequest.builder()
        .name("Robert")
        .address(Address.builder().street("13 Builder St.").zipcode(12345).build())
        .favColors(Arrays.asList("blue", "white"))
        .positionName("Builder")
        .build();

    mongoPersonDaoService.createPerson(request);
  }

  @Test
  @DisplayName("Create person on a non-empty database with explicit seed")
  @SeedWithDataset("onePersonToStart.json")
  @AssertMatchesDataset("expected2People.json")
  void createPersonWithExistingDataExplicitSeed() {

    CreatePersonRequest request = CreatePersonRequest.builder()
        .name("Robert")
        .address(Address.builder().street("13 Builder St.").zipcode(12345).build())
        .favColors(Arrays.asList("blue", "white"))
        .positionName("Builder")
        .build();

    mongoPersonDaoService.createPerson(request);
  }

  @Test
  @DisplayName("Create person on a non-empty database with classpath root datasets")
  @SeedWithDataset(
      value = "common/createPersonWithExistingData-seed.json",
      locationType = LocationType.CLASSPATH_ROOT)
  @AssertMatchesDataset(
      value = "common/createPersonWithExistingData-expected.json",
      locationType = LocationType.CLASSPATH_ROOT
  )
  void createPersonWithExistingDataWithPackageRelative() {

    CreatePersonRequest request = CreatePersonRequest.builder()
        .name("Robert")
        .address(Address.builder().street("13 Builder St.").zipcode(12345).build())
        .favColors(Arrays.asList("blue", "white"))
        .positionName("Builder")
        .build();

    mongoPersonDaoService.createPerson(request);
  }

  @Test
  @DisplayName("Update person")
  @SeedWithDataset("createPersonWithExistingData-seed.json")
  @AssertMatchesDataset
  void updatePerson() {

    UpdatePersonRequest updateRequest =
        new UpdatePersonRequest(
            "5db7545b7b615c739732c777",
            "Builder",
            "Robert",
            Arrays.asList("red", "green"),
            new Address("12 Builder St.", 12345));
    mongoPersonDaoService.updatePerson(updateRequest);

    // Any other API functions can be called here and asserted as usual
    Person updatedPerson = mongoPersonDaoService.getPerson("5db7545b7b615c739732c777");
    assertTrue(
        updatedPerson.getCreated().compareTo(updatedPerson.getUpdated()) < 0,
        "Updated data should be after created date");
  }

  @Test
  @DisplayName("Update person - Manual MongoUnit Testing")
  void updatePersonManualTest() {

    // Seed with data
    MongoUnit.seedWithDataset("createPersonWithExistingData-seed.json", this.getClass());

    // Perform API action
    UpdatePersonRequest updateRequest =
        new UpdatePersonRequest(
            "5db7545b7b615c739732c777",
            "Builder",
            "Robert",
            Arrays.asList("red", "green"),
            new Address("12 Builder St.", 12345));
    mongoPersonDaoService.updatePerson(updateRequest);

    // Any other API functions can be called here and asserted as usual
    Person updatedPerson = mongoPersonDaoService.getPerson("5db7545b7b615c739732c777");
    assertTrue(

```

--------------------------------

### toDatabase

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnitUtil.html

Seeds a MongoDB database with the provided dataset.

```APIDOC
## toDatabase

### Description
Seeds an existing database provided by 'mongoDatabase' with dataset represented in the `MongoUnitCollection`s schema by the provided 'jsonMongoUnitCollections'.

### Method Signature
`static void toDatabase(List<MongoUnitCollection> mongoUnitCollections, com.mongodb.client.MongoDatabase mongoDatabase, MongoUnitProperties mongoUnitProperties)`
```

--------------------------------

### DatasetGeneratorArguments.DatasetGeneratorArgumentsBuilder.build()

Source: https://mongounit.org/javadoc/org/mongounit/class-use/DatasetGeneratorArguments.html

The build() method of DatasetGeneratorArguments.DatasetGeneratorArgumentsBuilder is used to construct an instance of DatasetGeneratorArguments.

```APIDOC
## Method: DatasetGeneratorArguments.DatasetGeneratorArgumentsBuilder.build()

### Description
Constructs and returns a new DatasetGeneratorArguments object based on the builder's configuration.

### Returns
- **DatasetGeneratorArguments**: A fully constructed DatasetGeneratorArguments object.
```

--------------------------------

### createDatabaseGuardConfiguration

Source: https://mongounit.org/javadoc/org/mongounit/config/MongoUnitConfiguration.html

This static method creates a BeanDefinitionRegistryPostProcessor that protects the configured database from being wiped out by MongoUnit and test method execution.

```APIDOC
## createDatabaseGuardConfiguration

### Description
Creates a BeanDefinitionRegistryPostProcessor to protect the database during testing.

### Method
`static`

### Returns
`BeanDefinitionRegistryPostProcessor` - Protects the configured database from being wiped out by the MongoUnit and test method execution.
```

--------------------------------

### assertMatchesEmptyDataset

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnit.html

Asserts that the database is empty.

```APIDOC
## assertMatchesEmptyDataset()

### Description
Asserts database is empty.

### Method
static void
```

--------------------------------

### AssertionResult Builder

Source: https://mongounit.org/javadoc/org/mongounit/model/AssertionResult.html

How to use the builder pattern to create AssertionResult instances.

```APIDOC
## builder()

### Description
Provides a static method to obtain an instance of the builder pattern for the AssertionResult class.

### Method
`static AssertionResult.AssertionResultBuilder builder()`

### Returns
Instance of the builder pattern version of the `AssertionResult` class.
```

--------------------------------

### MongoUnitCollection Constructors

Source: https://mongounit.org/javadoc/org/mongounit/model/MongoUnitCollection.html

Provides constructors for creating MongoUnitCollection instances.

```APIDOC
## MongoUnitCollection()

### Description
Default constructor for creating an empty MongoUnitCollection.

### Constructor
`MongoUnitCollection()`
```

```APIDOC
## MongoUnitCollection(String collectionName, List<Map<String,Object>> documents)

### Description
Constructor to initialize a MongoUnitCollection with a collection name and a list of documents.

### Parameters
* **collectionName** (String) - Required - Name of the collection.
* **documents** (List<Map<String,Object>>) - Required - List of maps representing documents in the collection.

### Constructor
`MongoUnitCollection(String collectionName, List<Map<String,Object>> documents)`
```

--------------------------------

### MongoUnitUtil.retrieveResourceFromFile

Source: https://mongounit.org/javadoc/org/mongounit/class-use/MongoUnitException.html

Retrieves resource content from a file at a specified location, considering location type and relative package context.

```APIDOC
## MongoUnitUtil.retrieveResourceFromFile

### Description
Retrieves resource content from a file at a specified location, considering location type and relative package context.

### Method Signature
`static String` MongoUnitUtil.`retrieveResourceFromFile(String location, LocationType locationType, Class<?> relativePackageClass, String testClassName)`
```

--------------------------------

### fromDatabase

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnitUtil.html

Retrieves a dataset from a MongoDB database.

```APIDOC
## fromDatabase

### Description
Returns a list of `MongoUnitCollection`s that represents the dataset stored in the provided 'mongoDatabase'.

### Method Signature
`static List<MongoUnitCollection> fromDatabase(com.mongodb.client.MongoDatabase mongoDatabase, MongoUnitProperties mongoUnitProperties, List<String> preserveBsonTypes, String... collectionNames)`
```

--------------------------------

### generateNewMongoClientURI

Source: https://mongounit.org/javadoc/index-all.html

Generates a new MongoClientURI based on properties or environment.

```APIDOC
## generateNewMongoClientURI(String, boolean, String)

### Description
Generates a new MongoClientURI.

### Method
Static method

### Class
org.mongounit.config.MongoUnitConfigurationUtil
```

```APIDOC
## generateNewMongoClientURI(Environment)

### Description
Returns new `MongoClientURI` instance that contains newly generated URI, based on 'mongounit.properties'.

### Method
Static method

### Class
org.mongounit.config.MongoUnitConfigurationUtil
```

--------------------------------

### seedWithDataset

Source: https://mongounit.org/javadoc/org/mongounit/MongoUnit.html

Seeds the database with specified datasets.

```APIDOC
## seedWithDataset(String[] locations, Class<?> testClass)

### Description
Seeds the database with the JSON-based datasets pointed to by the provided 'locations' path array.

### Method
static List<MongoUnitCollection>

### Parameters
#### Path Parameters
- **locations** (String[]) - Required - Array of paths to JSON dataset files.
- **testClass** (Class<?>) - Required - The test class context.
```

```APIDOC
## seedWithDataset(String[] locations, LocationType locationType, Class<?> relativePackageClass)

### Description
Seeds the database with the JSON-based datasets pointed to by the provided 'locations' path array.

### Method
static List<MongoUnitCollection>

### Parameters
#### Path Parameters
- **locations** (String[]) - Required - Array of paths to JSON dataset files.
- **locationType** (LocationType) - Required - Type of location for the datasets.
- **relativePackageClass** (Class<?>) - Required - The class to determine the relative package for dataset locations.
```

```APIDOC
## seedWithDataset(String location, Class<?> testClass)

### Description
Seeds the database with the JSON-based datasets pointed to by the provided 'locations' path array.

### Method
static List<MongoUnitCollection>

### Parameters
#### Path Parameters
- **location** (String) - Required - Path to a JSON dataset file.
- **testClass** (Class<?>) - Required - The test class context.
```
Tokens:
Raw