JSONassert

简介

用更少的代码编写JSON单元测试。非常适合用来测试REST接口

JSON代码测试就像比较字符串。 JSONassert将字符串转换为JSON对象，并将逻辑结构和数据与实际JSON进行比较。当strict（严格模式）设置为false（推荐设置）时，它会允许数据重排序以及结果可扩展（只要对比的JSON包含了所有预期JSON的所有字段），从而使测试不那么脆弱。

支持的测试框架：

JUnit

JSONassert当前版本为1.5.0

示例

使用JSONassert，你可以编写并维护以下代码：

JSONObject data = getRESTData("/friends/367.json");
String expected = "{friends:[{id:123,name:\"Corby Page\"},{id:456,name:\"Carter Page\"}]}";
JSONAssert.assertEquals(expected, data, false);

而不用这样：

JSONObject data = getRESTData("/friends/367.json");
Assert.assertTrue(data.has("friends"));
Object friendsObject = data.get("friends");
Assert.assertTrue(friendsObject instanceof JSONArray);
JSONArray friends = (JSONArray) friendsObject;
Assert.assertEquals(2, data.length());
JSONObject friend1Obj = friends.getJSONObject(data.get(0));
Assert.true(friend1Obj.has("id"));
Assert.true(friend1Obj.has("name"));
JSONObject friend2Obj = friends.getJSONObject(data.get(1));
Assert.true(friend2Obj.has("id"));
Assert.true(friend2Obj.has("name"));
if ("Carter Page".equals(friend1Obj.getString("name"))) {
  Assert.assertEquals(123, friend1Obj.getInt("id"));
  Assert.assertEquals("Corby Page", friend2Obj.getString("name"));
  Assert.assertEquals(456, friend2Obj.getInt("id"));
}
else if ("Corby Page".equals(friend1Obj.getString("name"))) {
  Assert.assertEquals(456, friend1Obj.getInt("id"));
  Assert.assertEquals("Carter Page", friend2Obj.getString("name"));
  Assert.assertEquals(123, friend2Obj.getInt("id"));
}
else {
  Assert.fail("Expected either Carter or Corby, Got: " + friend1Obj.getString("name"));
}

报错消息

JSONassert的报错消息简洁明了，尤其在对比很长的JSON串时，你可以不用肉眼逐行查错，例如在以下代码中：

String expected = "{id:1,name:\"Joe\",friends:[{id:2,name:\"Pat\",pets:[\"dog\"]},{id:3,name:\"Sue\",pets:[\"bird\",\"fish\"]}],pets:[]}";
String actual = "{id:1,name:\"Joe\",friends:[{id:2,name:\"Pat\",pets:[\"dog\"]},{id:3,name:\"Sue\",pets:[\"cat\",\"fish\"]}],pets:[]}"
JSONAssert.assertEquals(expected, actual, false);

其返回结果：

friends[id=3].pets[]: Expected bird, but not found ; friends[id=3].pets[]: Contains cat, but not expected

它会告诉你在friends下，pets数列中id为3的对象不包含"bird"，而是"cat"（或许是猫吃了鸟？）

快速上手

首先导入JAR包，或者把以下语句添加到pom.xml

<dependency>
  <groupId>org.skyscreamer</groupId>
  <artifactId>jsonassert</artifactId>
  <version>1.5.0</version>
</dependency>

语法与JUnit Assert类似：

JSONAssert.assertEquals(expectedJSON, actualJSON, strictMode);//（预期JSON，实际JSON，是否开启严格模式）

添加JSON assert到现有的JUnit的测试当中，就像添加普通的Assert方法一样：

@Test
public void testGetUser() {
  Assert.assertTrue(_restService.isEnabled());
  String result = _restService.get("/user/123.json");
  JSONAssert.assertEquals("{id:123,name:\"Joe\"}", result, false);
}

为了使测试不显得那么脆弱，建议关掉严格模式。除非你要求比较的JSON与预期的JSON中数组顺序相同，或者要求两者具有相同的字段。

实践

断言参数可以是JSON的String串，JSONObject或者是JSONArray。为了可读性，以下示例均使用String串。

一个简单的示例，获取一个JSON对象并测试id是否相等：

@Test
public void testSimple() {
  String result = getJSONResult("/user/1.json");
  JSONAssert.assertEquals("{id:1}", result, false); // 通过
}

如果你启用了了严格模式，这时增加字段会比对失败：

String result = "{id:1,name:\"Juergen\"}";
JSONAssert.assertEquals("{id:1}", result, false); // 通过
JSONAssert.assertEquals("{id:1}", result, true); // 失败 因为严格模式下实际与预期的数量必须匹配

不管是否启用严格模式，字段顺序不影响测试结果：

String result = "{id:1,name:\"Juergen\"}";
JSONAssert.assertEquals("{name:\"Juergen\",id:1}", result, true); // 通过

由于应用接口随着业务的成熟而不断的扩展，所以推荐关掉严格模式，除了特定情形。

数组规则有些不同，如果比较在意连续性，可以打开严格模式：

String result = "[1,2,3,4,5]";
JSONAssert.assertEquals("[1,2,3,4,5]", result, true); // 通过
JSONAssert.assertEquals("[5,3,2,1,4]", result, true); // 失败 因为严格模式下数组元素顺序必须相同

当严格模式关闭时，数组元素可以为任意顺序：

String result = "[1,2,3,4,5]";
JSONAssert.assertEquals("[5,3,2,1,4]", result, false); // 通过

不管是否开启了严格模式，数组元素必须匹配。不像字段在关闭严格模式下可以不匹配：

String result = "[1,2,3,4,5]";
JSONAssert.assertEquals("[1,2,3,4,5]", result, false); // 通过 因为数组元素匹配
JSONAssert.assertEquals("[1,2,3]", result, false); // 失败 因为数组元素比预期的多
JSONAssert.assertEquals("[1,2,3,4,5,6]", result, false); // 失败 因为数组元素比预期的少

以上示例都很简单，但JSONassert可以适用于任何大小（取决于虚拟机内存大小）、深度或者更复杂的JSON。

你可以测试嵌套数组，宽松/严格的顺序限制适用于每一层级：

String result = "{id:1,stuff:[[1,2],[2,3],[],[3,4]]}";
JSONAssert.assertEquals("{id:1,stuff:[[1,2],[2,3],[],[3,4]]}", result, true); // 通过
JSONAssert.assertEquals("{id:1,stuff:[[4,3],[3,2],[],[1,2]]}", result, false); // 通过

String result = "{id:1,name:\"Joe\",friends:[{id:2,name:\"Pat\",pets:[\"dog\"]},{id:3,name:\"Sue\",pets:[\"bird\",\"fish\"]}],pets:[]}";
JSONAssert.assertEquals("{id:1,name:\"Joe\",friends:[{id:2,name:\"Pat\",pets:[\"dog\"]},{id:3,name:\"Sue\",pets:[\"bird\",\"fish\"]}],pets:[]}", result, true); // 通过
JSONAssert.assertEquals("{name:\"Joe\",friends:[{id:3,name:\"Sue\",pets:[\"fish\",\"bird\"]},{id:2,name:\"Pat\",pets:[\"dog\"]}],pets:[],id:1}", result, false); // 通过

如下所示，测试可以适用于任何深度级别：

String result = "{a:{b:{c:{d:{e:{f:{g:{h:{i:{j:{k:{l:{m:{n:{o:{p:\"blah\"}}}}}}}}}}}}}}}}";
JSONAssert.assertEquals("{a:{b:{c:{d:{e:{f:{g:{h:{i:{j:{k:{l:{m:{n:{o:{p:\"blah\"}}}}}}}}}}}}}}}}", result, true); // 通过

几个实用类

JSONCompare

该类作为JSONAssert的具体实现，可以单独作为一个工具类在代码中使用。包含7个比较JSON的重载方法，参数覆盖String、JSONObject、JSONArray等常用类型。比较可以使用内置的比较模式，也可以使用自定义的比较器，不建议使用第7个仅有两个参数的方法，因为该方法仅调用equals()来判定两个JSON是否相等。

可以对比JSON字符串、JSONObject、JSONArray

使用内置的比较模式

JSONCompareMode

预期JSON：

{
    "key1":"value",
    "object":{
        "key2":"value"
    },
    "array":[
        "arr1",
        "arr2",
        "arr3"
    ]
}

测试严格模式JSON：

{
    "object":{
        "key2":"value"
    },
    "key1":"value",
    "array":[
        "arr1",
        "arr2",
        "arr3"
    ]
}

//测试通过，比较串与预期串每个元素键值对均相同，数组内元素与预期排序相同。
JSONCompare.compareJSON(expectedStr, actualStr1, JSONCompareMode.STRICT);

注意：JSON对象内元素的排序不影响判断结果。

测试宽松模式JSON：

{
    "array":[
        "arr3",
        "arr2",
        "arr1"
    ],
    "object":{
        "key2":"value"
    },
    "key1":"value",
    "key3":"value"
}

//测试通过，比较串包含并匹配所有预期串元素的键值对，数组内元素排序不影响结果。
JSONCompare.compareJSON(expectedStr, actualStr2, JSONCompareMode.LENIENT);

测试不可扩展模式JSON：

{
    "array":[
        "arr3",
        "arr2",
        "arr1"
    ],
    "object":{
        "key2":"value"
    },
    "key1":"value"
}

//测试通过，比较串与预期串每个元素键值对均相同，数组内元素排序不影响结果。
JSONCompare.compareJSON(expectedStr, actualStr3, JSONCompareMode.NON_EXTENSIBLE);

测试严格排序模式JSON：

{
    "key1":"value",
    "object":{
        "key2":"value"
    },
    "array":[
        "arr1",
        "arr2",
        "arr3"
    ],
    "key3":"value"
}

//测试通过，比较串包含并匹配所有预期串元素的键值对，数组内元素与预期排序相同。
JSONCompare.compareJSON(expectedStr, actualStr4, JSONCompareMode.STRICT_ORDER);

注意：JSON对象内元素的排序不影响判断结果。

使用自定义比较器

如果内置的比较模式或者比较器不满足需要，可以实现JSONComparator接口或继承DefaultComparator、CustomComparator等类来自定义比较器，以下为继承DefaultComparator来实现数值与数值型字符串也可以进行比较：

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
import org.skyscreamer.jsonassert.Customization;
import org.skyscreamer.jsonassert.JSONCompareMode;
import org.skyscreamer.jsonassert.JSONCompareResult;
import org.skyscreamer.jsonassert.ValueMatcherException;
import org.skyscreamer.jsonassert.comparator.CustomComparator;
import org.skyscreamer.jsonassert.comparator.JSONComparator;

import java.util.Arrays;
import java.util.Collection;
import java.util.regex.Pattern;

/**
 * @Author: liu
 * @Date: 2020/11/30 17:42
 */
public class MyCustomComparator extends CustomComparator {  //这里选择继承内置的CustomComparator

    private final Collection<Customization> customizations;

    public MyCustomComparator(JSONCompareMode mode, Customization... customizations) {
        super(mode);
        this.customizations = Arrays.asList(customizations);
    }

    //比较器默认调用此方法，如果要实现复杂逻辑，可以重写
    @Override
    public void compareValues(String prefix, Object expectedValue, Object actualValue, JSONCompareResult result) throws JSONException {
        Customization customization = getCustomization(prefix);
        if (customization != null) {
            try {
                if (!customization.matches(prefix, actualValue, expectedValue, result)) {
                    result.fail(prefix, expectedValue, actualValue);
                }
            }
            catch (ValueMatcherException e) {
                result.fail(prefix, e);
            }
        } else {
            if (expectedValue == actualValue) {
                return;
            }
            if ((expectedValue == null && actualValue != null) || (expectedValue != null && actualValue == null)) {
                result.fail(prefix, expectedValue, actualValue);
            }
            if (areNumbers(expectedValue, actualValue)) {   //这里判定值是否为数字
                if (areNotSameDoubles(expectedValue, actualValue)) {
                    result.fail(prefix, expectedValue, actualValue);
                }
            } else if (expectedValue.getClass().isAssignableFrom(actualValue.getClass())) {
                if (expectedValue instanceof JSONArray) {
                    compareJSONArray(prefix, (JSONArray) expectedValue, (JSONArray) actualValue, result);
                } else if (expectedValue instanceof JSONObject) {
                    compareJSON(prefix, (JSONObject) expectedValue, (JSONObject) actualValue, result);
                } else if (!expectedValue.equals(actualValue)) {
                    result.fail(prefix, expectedValue, actualValue);
                }
            } else {
                result.fail(prefix, expectedValue, actualValue);
            }
        }
    }

    //重写是否为数字的判定条件
    @Override
    protected boolean areNumbers(Object expectedValue, Object actualValue) {
        if (expectedValue instanceof Number && actualValue instanceof Number) {
            return true;
        } else if (isInteger(expectedValue.toString()) && isInteger(actualValue.toString())){
            return true;
        } else {
            return false;
        }
    }

    //重写两位数字相等的判定条件
    @Override
    protected boolean areNotSameDoubles(Object expectedValue, Object actualValue) {
        if (expectedValue instanceof String || actualValue instanceof String) {
            expectedValue = Double.valueOf(expectedValue.toString());
            actualValue = Double.valueOf(actualValue.toString());
        }
        return ((Number) expectedValue).doubleValue() != ((Number) actualValue).doubleValue();
    }

    public static boolean isInteger(String str) {
        Pattern pattern = Pattern.compile("^[-\\+]?[\\d]*$");
        return pattern.matcher(str).matches();
    }

    private Customization getCustomization(String path) {
        for (Customization c : customizations) {
            if (c.appliesToPath(path)) {
                return c;
            }
        }
        return null;
    }
}

测试的预期JSON：

{
    "key1":"10",
    "object":{
        "key2":"value"
    },
    "array":[
        "arr1",
        "arr2",
        "arr3"
    ]
}

测试的比较JSON：

{
    "key1":10,
    "object":{
        "key2":"value"
    },
    "array":[
        "arr1",
        "arr2",
        "arr3"
    ]
}

//结果为true
JSONCompare.compareJSON(expectedStr10, actualStr10, new MyCustomComparator(JSONCompareMode.LENIENT));

JSONCompareResult

该类主要为JSONCompare的结果返回实体类，包含是否通过以及比对失败信息。

JSONCompareResult result = JSONCompare.compareJSON(expectedStr10, actualStr10, new MyCustomComparator(JSONCompareMode.LENIENT));
        System.out.println("自定义比较器 \n是否通过: " + result.passed() + "\n错误信息: " + result.getMessage());

控制台结果：

JSONAssert

该类主要用于单元测试，用法与JSONCompare类似。

其包含默认的严格模式，仅需传true/false：

public static void assertEquals(JSONObject expected, JSONObject actual, boolean strict)
            throws JSONException {
        assertEquals(expected, actual, strict ? JSONCompareMode.STRICT : JSONCompareMode.LENIENT);
    }

另外可以自定义消息前缀，便于定位问题：

        @Test
    public void testJSONAssert() throws JSONException {
        String expectedStr10 = "{\"key1\":\"10\"}";
        String actualStr10 = "{\"key1\":\"11\"}";
        JSONAssert.assertEquals("自定义消息前缀：", expectedStr10, actualStr10, false);
    }