ekino / jcv

JSON Content Validator (JCV) allows you to compare JSON contents with embedded validation.

{#JCV#}

JSON Content Validator (JCV) allows you to compare JSON contents with embedded validation.

Table of contents

• Summary
• Examples
• Quick start
  • Core module
  • AssertJ module
  • Hamcrest module
  • WireMock module
• Validators

Summary

Make a full json content assertion using the minimum amount of code using an expected JSON content with the possibility to add custom field validation.

Make your tests light, easy to write, readable and exhaustive.

This tool is based on the very useful JSONassert one and add the embedded validation system to assert unpredicatable values.

Examples

The actual JSON you want to validate :

{
    "field_1": "some value",
    "field_2": "3716a0cf-850e-46c3-bd97-ac1f34437c43",
    "date": "2011-12-03T10:15:30Z",
    "other_fields": [{
        "id": "2",
        "link": "https://another.url.com/my-base-path/query?param1=true"
    }, {
        "id": "1",
        "link": "https://some.url.com"
    }]
}

The expected JSON with embedded validation :

{
   "field_1": "some value",
   "field_2": "{#uuid#}",
   "date": "{#date_time_format:iso_instant#}",
   "other_fields": [{
       "id": "1",
       "link": "{#url#}"
   }, {
       "id": "2",
       "link": "{#url_ending:query?param1=true#}"
   }]
}

More examples available here : ekino/jcv-examples

Quick start

Core module

JCV add a new JSONComparator implementation to make the possibility to use validators inside the expected JSON, so it requires the JSONassert dependency to work.

Dependencies

Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.skyscreamer</groupId>
    <artifactId>jsonassert</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.ekino.oss.jcv</groupId>
    <artifactId>jcv-core</artifactId>
    <version>1.6.0-SNAPSHOT</version>
    <scope>test</scope>
  </dependency>
  ...
</dependencies>

Gradle

dependencies {
  ...
  testImplementation 'org.skyscreamer:jsonassert:1.5.0'
  testImplementation 'com.ekino.oss.jcv:jcv-core:1.6.0-SNAPSHOT'
  ...
}

Note:

Do not forget to add the maven snapshots repository for SNAPSHOT versions :

Maven

<repositories>
  ...
  <repository>
    <id>maven-snapshots</id>
    <url>http://oss.sonatype.org/content/repositories/snapshots</url>
    <layout>default</layout>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  ...
</repositories>

Gradle

repositories {
    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots/")
    }
}

AssertJ module

A JCV module that supports AssertJ.

Example

import static com.ekino.oss.jcv.assertion.assertj.JsonCompareAssert.*;

@Test
void testContainsValidator() throws JSONException {
    assertThatJson("{\"field_name\": \"hello world!\"}")
        .isValidAgainst("{\"field_name\": \"{#contains:llo wor#}\"}");
}

Dependencies

Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.skyscreamer</groupId>
    <artifactId>jsonassert</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <version>3.9.1</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.ekino.oss.jcv</groupId>
    <artifactId>jcv-assertj</artifactId>
    <version>1.6.0-SNAPSHOT</version>
    <scope>test</scope>
  </dependency>
  ...
</dependencies>

Gradle

dependencies {
  ...
  testImplementation 'org.skyscreamer:jsonassert:1.5.0'
  testImplementation 'org.assertj:assertj-core:3.9.1'
  testImplementation 'com.ekino.oss.jcv:jcv-assertj:1.6.0-SNAPSHOT'
  ...
}

Hamcrest module

A JCV module that supports Hamcrest.

Example

import static com.ekino.oss.jcv.assertion.hamcrest.JsonMatchers.*;
import static org.hamcrest.MatcherAssert.*;

@Test
void testContainsValidator() throws JSONException {
    assertThat(
        "{\"field_name\": \"hello world!\"}",
        jsonMatcher("{\"field_name\": \"{#contains:llo wor#}\"}")
    );
}

Dependencies

Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.skyscreamer</groupId>
    <artifactId>jsonassert</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>hamcrest</artifactId>
    <version>2.1</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.ekino.oss.jcv</groupId>
    <artifactId>jcv-hamcrest</artifactId>
    <version>1.6.0-SNAPSHOT</version>
    <scope>test</scope>
  </dependency>
  ...
</dependencies>

Gradle

dependencies {
  ...
  testImplementation 'org.skyscreamer:jsonassert:1.5.0'
  testImplementation 'org.hamcrest:hamcrest:2.1'
  testImplementation 'com.ekino.oss.jcv:jcv-hamcrest:1.6.0-SNAPSHOT'
  ...
}

WireMock module

A JCV module extension for WireMock.

Example

Register the extension on your WireMock server:

import com.github.tomakehurst.wiremock.WireMockServer
import com.github.tomakehurst.wiremock.core.WireMockConfiguration
import com.ekino.oss.jcv.assertion.wiremock.JcvRequestMatcherExtension

private val wireMockServer by lazy {
  WireMockServer(
    WireMockConfiguration()
      .dynamicPort()
      .extensions(JcvRequestMatcherExtension())
  )
}

Then you can stub via code:

import com.github.tomakehurst.wiremock.client.WireMock.aResponse
import com.github.tomakehurst.wiremock.client.WireMock.post
import com.github.tomakehurst.wiremock.client.WireMock.urlEqualTo
import com.ekino.oss.jcv.assertion.wiremock.JcvRequestMatcherExtension

wireMockServer.stubFor(
  post(urlEqualTo("/some_url"))
    .andMatching(
      JcvRequestMatcherExtension.toRequestMatcher(
        json =
        """
        {
          "some_field": "{#not_empty#}"
        }
        """
      )
    )
    .willReturn(
      aResponse()
        .withHeader("Content-Type", "text/plain")
        .withStatus(200)
        .withBody("OK")
    )
)

Or you can stub via mapping file:

{
  "request": {
    "method": "POST",
    "url": "/some_url",
    "customMatcher": {
      "name": "equalToJcv",
      "parameters": {
        "json": {
          "some_field": "{#not_empty#}"
        },
        "ignoreArrayOrder": true,
        "ignoreExtraElements": false
      }
    }
  },
  "response": {
    "status": 200,
    "body": "OK"
  }
}

Dependencies

Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.skyscreamer</groupId>
    <artifactId>jsonassert</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.github.tomakehurst</groupId>
    <artifactId>wiremock-jre8</artifactId>
    <version>2.27.2</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.ekino.oss.jcv</groupId>
    <artifactId>jcv-wiremock</artifactId>
    <version>1.6.0-SNAPSHOT</version>
    <scope>test</scope>
  </dependency>
  ...
</dependencies>

Gradle

dependencies {
  ...
  testImplementation 'org.skyscreamer:jsonassert:1.5.0'
  testImplementation 'com.github.tomakehurst:wiremock-jre8:2.27.2'
  testImplementation 'com.ekino.oss.jcv:jcv-wiremock:1.6.0-SNAPSHOT'
  ...
}

Learn more

You will find more information (validators, guided tours...) in the Wiki.

jcv's Issues

Migrate to Github actions

Make jsonMatcher strict by default

Hello,
I was wondering if it would be nicer to have the usually used jsonMatcher() method strict by default (.mode(JSONCompareMode.STRICT)). Moreover we could add another method like unorderedJsonMatcher() to perform assertions when the order can change.

This would be somehow like what we have in assertj.

What do you think about that ?

Provide a changelog

Hi,

Could you please provide a changelog listing the changes between two releases ? It would help this library consumers a lot.

Thanks :)

Strict typing in comparators may produce a ClassCastException

A JsonValueComparator uses the same type for the actual and expected parameters. This may be problematic when the actual type is not the same as the expected type.

Here's an example:

Actual is

{
 "date": null
}

Expected is

{
 "date": "{#date_time_format:iso_instant#}"
}

A ClassCastException will be thrown because "date" will be "deserialized" as a null JSONObject, and DateTimeFormatComparator expects an actual of type String.

Add wiremock module

Hi,

it could be cool to provide a wiremock module to validate request or response body json with JCV validators.

In wiremock, when we try to compare a json array with another one but not in the same order, the EqualToJsonPattern doesn't match. ( here is an issue in wiremock repository : https://github.com/tomakehurst/wiremock/issues/1230 ). If we use a JCV with wiremock it should fix this.

If you want to test the current EqualToJsonPattern error, here is a test :

@Test
  void reproduceFailingIgnoreArrayOrder() {
    var expected = "{ \"array\": [\"a\",\"b\",\"c\",\"d\",\"e\",\"f\",\"g\",\"h\"] }";
    var actual = "{ \"array\": [\"b\",\"a\",\"d\",\"c\",\"e\",\"f\",\"g\",\"h\"] }";
    var pattern = new EqualToJsonPattern(expected, true, false);
    var result = pattern.match(actual);
    var exact = result.isExactMatch();
    assertTrue(exact);
  }

Upgrade to Kotlin 1.4