Package org.mongounit

Class MongoUnitUtil

java.lang.Object
org.mongounit.MongoUnitUtil
public class MongoUnitUtil extends Object

  • Field Details

    • COMPARATOR_FIELD_NAME

      public static final String COMPARATOR_FIELD_NAME
      Field name to use when extracting the comparator field out of a special document which represents a MongoUnit value.
      See Also:

  • Constructor Details

    • MongoUnitUtil

      public MongoUnitUtil()

  • Method Details

    • fromDatabase

      public static List<MongoUnitCollection> fromDatabase(com.mongodb.client.MongoDatabase mongoDatabase, MongoUnitProperties mongoUnitProperties, List<String> preserveBsonTypes, String... collectionNames) throws IllegalArgumentException
      Returns a list of MongoUnitCollections that represents the dataset stored in the provided 'mongoDatabase'.
      Parameters:
      mongoDatabase - Instance of the MongoDB database with collections based on which to base the returned dataset.
      mongoUnitProperties - Collection of properties framework was configured with. If the provided 'preserveBsonTypes' is null, this argument may also be 'null' and is ignored.
      preserveBsonTypes - List of string representation of BsonType enum names that should be preserved when creating documents. This **must** be 'null' when this method is used for assertions instead of to output JSON through DatasetGenerator.
      collectionNames - Optional list of collection names to which to restrict data extraction to.
      Returns:
      List of MongoUnitCollections that represents the dataset stored in the provided 'mongoDatabase'. If 'collectionNames' are specified, the extracted dataset will be limited to those collections only.
      Throws:
      IllegalArgumentException - If at least one of the optionally specified 'collectionNames' does not exist in the provided 'mongoDatabase'.

    • toDatabase

      public static void toDatabase(List<MongoUnitCollection> mongoUnitCollections, com.mongodb.client.MongoDatabase mongoDatabase, MongoUnitProperties mongoUnitProperties) throws MongoUnitException
      Seeds an existing database provided by 'mongoDatabase' with dataset represented in the MongoUnitCollections schema by the provided 'jsonMongoUnitCollections'.
      Parameters:
      mongoUnitCollections - List of MongoUnitCollections to persist to seed the database with.
      mongoDatabase - MongoDB instance to seed with the provided data.
      mongoUnitProperties - Collection of properties framework was configured with.
      Throws:
      MongoUnitException - If anything goes wrong with interpreting the provided 'mongoUnitCollections' in order to seed the database.

    • dropAllCollectionsInDatabase

      public static void dropAllCollectionsInDatabase(com.mongodb.client.MongoDatabase mongoDatabase)
      Finds and drops all of the collections in the provided 'mongoDatabase'.
      Parameters:
      mongoDatabase - MongoDB reference in which to clear/drop all collections.

    • toMongoUnitTypedCollectionsFromJson

      public static List<MongoUnitCollection> toMongoUnitTypedCollectionsFromJson(String jsonMongoUnitCollections) throws MongoUnitException
      Parameters:
      jsonMongoUnitCollections - String JSON representation that conforms to the MongoUnitCollections schema.
      Returns:
      List of MongoUnitCollection objects represented by the provided JSON string 'jsonMongoUnitCollections'.
      Throws:
      MongoUnitException - If the provided 'jsonMongoUnitCollections' can not be interpreted to match the list of MongoUnitCollections.

    • generateMongoUnitValueDocument

      public static Map<String,Object> generateMongoUnitValueDocument(String fieldNameIndicator, String bsonType, Object value)
      Parameters:
      fieldNameIndicator - Field name indicator that is configured to be a trigger to recognize that the provided 'mongoUnitValueDocument' is using a special MongoUnit schema format.
      bsonType - String name of a BSON TYPE corresponding to the enum name of BsonType.
      value - The value to set for the 'value' part of the MongoUnit value document.
      Returns:
      A special MongoUnit value document with a single name/value pair where the name is the provided 'fieldNameIndicator' concatenated with the provided 'bsonType' and the value is the provided 'value'.

    • extractMongoUnitValue

      public static MongoUnitValue extractMongoUnitValue(Map<String,Object> mongoUnitValueDocument, String fieldNameIndicator) throws MongoUnitException
      Parameters:
      mongoUnitValueDocument - Map which contains keys in the special MongoUnit value format.
      fieldNameIndicator - Field name indicator that is configured to be a trigger to recognize that the provided 'mongoUnitValueDocument' is using a special MongoUnit schema format.
      Returns:
      Instance of MongoUnitValue which contains actual value, BsonType, and comparator.
      Throws:
      MongoUnitException - If no keys in the provided 'mongoUnitValueDocument' contain the special trigger indicator provided by 'fieldNameIndicator'.

    • assertMatches

      public static AssertionResult assertMatches(List<MongoUnitCollection> expected, List<MongoUnitCollection> actual, MongoUnitProperties mongoUnitProperties)
      Returns An AssertionResult with a 'match' of 'true' if the provided 'expected' and 'actual' lists of MongoUnitCollections match according to the MongoUnit framework rules, or with 'false' otherwise. Rules for matching: 1) Match is not effected if 'expected' is missing a field name in its definition. 2) Presence of a configurable special field name key ("$$" with the value to compare actual data with) in a document, allows framework to look for another special field "comparator". Its value can be either "=", "!=", ">", "<", ">=", "<=". The "=" is how every field value compared by default if the special document containing "comparator" is not present. "<" and ">" compare values to ensure one is less than or greater than the other. These comparisons will work for Strings, dates, date/time stamps, numbers (or any type that implements Comparable interface).
      Parameters:
      expected - List of MongoUnitCollections that the provided 'actual' dataset is to be compared against. An identical list is not necessarily to achieve a match and thus this list may contain special fields that guide the matching process.
      actual - List of MongoUnitCollections retrieved from the database after the target test call.
      mongoUnitProperties - Collection of properties framework was configured with.
      Returns:
      An AssertionResult with a 'match' of 'true' if the provided 'expected' and 'actual' lists of MongoUnitCollections match according to the MongoUnit framework rules, or with 'false' otherwise.

    • assertMatches

      public static AssertionResult assertMatches(MongoUnitCollection expected, MongoUnitCollection actual, MongoUnitProperties mongoUnitProperties) throws MongoUnitException
      Returns An AssertionResult with a 'match' of 'true' if the provided 'expected' and 'actual' MongoUnitCollections match according to the MongoUnit framework rules, or with 'false' otherwise. Rules for matching: 1) Match is not effected if 'expected' is missing a field name in its definition. 2) Presence of a configurable special field name key ("$$" with the value to compare actual data with) in a document, allows framework to look for another special field "comparator". Its value can be either "=", "!=", ">", "<", ">=", "<=". The "=" is how every field value compared by default if the special document containing "comparator" is not present. "<" and ">" compare values to ensure one is less than or greater than the other. These comparisons will work for Strings, dates, date/time stamps, numbers (or any type that implements Comparable interface).
      Parameters:
      expected - MongoUnitCollections that the provided 'actual' dataset is to be compared against. An identical list is not necessarily to achieve a match and thus this list may contain special fields that guide the matching process.
      actual - MongoUnitCollections retrieved from the database after the target test call.
      mongoUnitProperties - Collection of properties framework was configured with.
      Returns:
      An AssertionResult with a 'match' of 'true' if the provided 'expected' and 'actual' MongoUnitCollections match according to the MongoUnit framework rules, or with 'false' otherwise.
      Throws:
      MongoUnitException - If the expected collection name is null.

    • assertMatches

      public static AssertionResult assertMatches(Map<String,Object> expectedDocument, Map<String,Object> actualDocument, MongoUnitProperties mongoUnitProperties) throws MongoUnitException
      Returns an AssertionResult with a 'match' of 'true' if the provided 'expectedDocument' and 'actualDocument' match according to the MongoUnit framework rules, or with 'false' otherwise. Fields not included in the provided 'expectedDocument' are assumed irrelevant to the match.
      Parameters:
      expectedDocument - Map of field names with values that represent the expected document.
      actualDocument - Map of field names with values that represents actual document in the database.
      mongoUnitProperties - Collection of properties framework was configured with.
      Returns:
      An AssertionResult with a 'match' of 'true' if the provided 'expectedDocument' and 'actualDocument' match according to the MongoUnit framework rules, or with 'false' otherwise.
      Throws:
      MongoUnitException - If anything goes wrong with processing this assertion.

    • assertMatchesValue

      public static AssertionResult assertMatchesValue(Object expectedValue, Object actualValue, MongoUnitProperties mongoUnitProperties) throws MongoUnitException
      Parameters:
      expectedValue - Expected value.
      actualValue - Actual value retrieved from the database.
      mongoUnitProperties - Collection of properties framework was configured with.
      Returns:
      An AssertionResult with a 'match' of 'true' if the provided 'expectedValue' and 'actualValue' match according to the MongoUnit framework rules, or with 'false' otherwise.
      Throws:
      MongoUnitException - If anything goes wrong with processing this assertion.

    • assertMatchesMongoUnitValue

      public static AssertionResult assertMatchesMongoUnitValue(Map<String,Object> expectedMongoUnitValue, Object actualValue, String fieldNameIndicator) throws MongoUnitException
      Returns AssertionResult with a 'match' of 'true' if the provided 'expectedValue' and 'actualValue' match according to the MongoUnit framework rules, or with 'false' otherwise. The value of "comparator" can be either "=", "!=", ">", "<", ">=", "<=". The "=" is how every field value compared by default if the special document containing "comparator" is not present. "<" and ">" compare values to ensure one is less than or greater than the other. The ">=" and "<=" compare values to ensure one is less than or greater than or equal to the other. If the "comparator" field is not specified, it's assumed to be "=". ">" assertion is read: is expected greater than actual, i.e., expected > actual. "<" assertion is read: is expected less than actual, i.e., expected < actual, etc. These comparisons will ONLY work for strings, dates, date/time stamps, numbers (or any type that implements Comparable interface).
      Parameters:
      expectedMongoUnitValue - Expected value expressed as a special MongoUnit value document, including the "comparator" field which dictates how its "value" field value should be compared to the provided 'actualValue'.
      actualValue - Actual value extracted from the database.
      fieldNameIndicator - Field name indicator that is configured to be a trigger to recognize that the provided 'value' is using a special MongoUnit schema format.
      Returns:
      An AssertionResult with a 'match' of 'true' if the provided 'expectedValue' and 'actualValue' match according to the MongoUnit framework rules, or with 'false' otherwise.
      Throws:
      MongoUnitException - If the developer specified expected value appears not to be of type Comparable and therefore not supported.

    • compare

      public static int compare(Comparable expected, Comparable actual)
      Parameters:
      expected - Expected value to compare.
      actual - Actual value to compare.
      Returns:
      A negative integer, zero, or a positive integer as the expected is less than, equal to, or greater than the actual.

    • extractTestClassName

      public static String extractTestClassName(Class<?> testClass) throws MongoUnitException
      Parameters:
      testClass - Class instance of the test class.
      Returns:
      Name of the test class. If specified by the 'name' attribute of MongoUnitTest annotation. If not specified, it defaults to the simple class name of the testing class.
      Throws:
      MongoUnitException - If the provided 'testClass' does not have MongoUnitTest annotation on it.

    • extractMongoUnitDatasets

      public static MongoUnitDatasets extractMongoUnitDatasets(org.junit.jupiter.api.extension.ExtensionContext context, String testClassName, boolean classLevel) throws MongoUnitException
      Extracts MongoUnit datasets based on the potential class or method level MongoUnit annotations. The seed and assert datasets returned do not have same-named collections in the list of collections.
      Parameters:
      context - Extension context within which this method is being executed.
      testClassName - Name of the test class, which is either MongoUnitTest specified name or, if not specified, the simple class name of the test class.
      classLevel - If 'true', this method will treat this extraction on a class level, if 'false', on a method level.
      Returns:
      Instance of MongoUnitDatasets which potentially contains datasets to use for seeding the database as well as asserting a match against. The seed and assert datasets returned do not have same-named collections in the list of collections.
      Throws:
      MongoUnitException - If at least one AssertMatchesDataset annotation appears before any of the SeedWithDataset annotations or one of the annotations contains values for mutually exclusive properties.

    • combineNoRepeatingCollections

      public static List<MongoUnitCollection> combineNoRepeatingCollections(List<MongoUnitCollection> datasetWithRepeatingCollections)
      Parameters:
      datasetWithRepeatingCollections - List of MongoUnitCollections that may have the same collection repeated. Allowed to be 'null'.
      Returns:
      List of MongoUnitCollections where each collection does not repeat in the list while preserving the original order of documents. If the provided 'datasetWithRepeatingCollections' is 'null', an empty list is returned.

    • combineDatasets

      public static List<MongoUnitCollection> combineDatasets(List<MongoUnitCollection> dataset1, List<MongoUnitCollection> dataset2)
      Parameters:
      dataset1 - List of MongoUnitCollection representing first dataset. Can't be null.
      dataset2 - List of MongoUnitCollection representing second dataset. Can't be null.
      Returns:
      Single *new* list of MongoUnitCollections that contains only 1 list of documents per collection with the preserved order of data from 'dataset1' first, 'dataset2' second.

    • retrieveResourceFromFile

      public static String retrieveResourceFromFile(String location, LocationType locationType, Class<?> relativePackageClass, String testClassName) throws MongoUnitException
      Parameters:
      location - Path to the file.
      locationType - Type of location the provided 'location' is.
      relativePackageClass - If 'locationType' is 'CLASS', this is the class type whose package and class name (or name of MongoUnitTest) should be used for relativity of the provided 'location' path. Otherwise, it's ignored and can be null.
      testClassName - Name of the test class, which is either MongoUnitTest specified name or, if not specified, the simple class name of the test class.
      Returns:
      Contents of the file pointed to by the provided 'location', given the provided 'locationType'.
      Throws:
      MongoUnitException - If anything goes wrong loading the dataset from the provided 'location'.

    • getTestClassNamePath

      public static String getTestClassNamePath(Class<?> packagedClass)
      Parameters:
      packagedClass - Class based on whose package the returned path is constructed. Can be 'null'.
      Returns:
      'null' if the provided 'relativePackageClass' is 'null', otherwise, a string that consists of a leading '/' followed by 'relativePackageClass' package name converted into a path combined with trailing '/'.

    • getFileLocations

      public static String[] getFileLocations(org.junit.jupiter.api.extension.ExtensionContext context, String[] value, String[] locations, boolean classLevel, String testClassName, String fileEndingAndExtension)
      Parameters:
      context - Test execution context within which the test is being executed.
      value - Value of the 'value' part of xxxDataset annotation.
      locations - Value of the 'locations' part of the xxxDataset annotation.
      classLevel - True if extracted values were at the class level, false otherwise.
      testClassName - Name of the test class, which is either MongoUnitTest specified name or, if not specified, the simple class name of the test class.
      fileEndingAndExtension - String that contains some ending with an extension. (Usually '-seed.json' or '-expected.json' for seeding and assertions accordingly.
      Returns:
      Array of locations. Check if 'value' or 'locations' is a non-empty array. If both are empty, uses 'testClassName' and 'standardExtension' to generate a default file name location based on whether or not this data was from a class level annotation or method level one (which is determined by the provided 'classLevel').

    • retrieveDatasetFromLocations

      public static List<MongoUnitCollection> retrieveDatasetFromLocations(String[] fileLocations, LocationType locationType, Class<?> relativePackageClass, String testClassName) throws MongoUnitException
      Returns List of MongoUnitCollections based on the data pointed to by provided 'fileLocations'. NOTE: returns datasets that may repeat the same collection.
      Parameters:
      fileLocations - Array paths to the files containing datasets.
      locationType - Type of location the provided 'fileLocations' are.
      relativePackageClass - If 'locationType' is 'CLASS', this is the class type whose package should be used for package relative 'location' path. Otherwise, it's ignored and can be null.
      testClassName - Name of the test class, which is either MongoUnitTest specified name or, if not specified, the simple class name of the test class.
      Returns:
      List of MongoUnitCollections based on the data pointed to by provided 'fileLocations'.
      Throws:
      MongoUnitException - If 'value' or 'locations' point to a file that does not exist or neither 'value' nor 'locations' specify any locations at all and standard locations were likewise unsuccessful.