From ba284f65182220faa75598d816e36e85d25f928d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=87=91=E6=88=9F?= Date: Fri, 16 Dec 2022 23:09:19 +0800 Subject: [PATCH] doc: introduce CollectionTool class --- docs/en-us/doc/collection-tools.md | 131 +++++++++++++++++++++++++++++ docs/en-us/doc/setup.md | 1 + docs/en-us/sidebar.md | 1 + docs/zh-cn/doc/annotations.md | 13 +-- docs/zh-cn/doc/collection-tools.md | 129 ++++++++++++++++++++++++++++ docs/zh-cn/doc/setup.md | 1 + docs/zh-cn/sidebar.md | 1 + 7 files changed, 272 insertions(+), 5 deletions(-) create mode 100644 docs/en-us/doc/collection-tools.md create mode 100644 docs/zh-cn/doc/collection-tools.md diff --git a/docs/en-us/doc/collection-tools.md b/docs/en-us/doc/collection-tools.md new file mode 100644 index 0000000..8451d1b --- /dev/null +++ b/docs/en-us/doc/collection-tools.md @@ -0,0 +1,131 @@ +Collection Tools +--- + +During test data preparation, various collection types are often used. However, collection data initialization in Java needs series of redundant call to the `add()` or `put()` method, making the code very tedious. + +Inspired by the collection operations of Kotlin language, `TestableMock` draws on a set of concise collection construction method, which makes the creation of Java collection objects elegant. + +The utility class `CollectionTool` provides following global static methods: + +## arrayOf + +Quickly construct an array of any type, equivalent to Kotlin's `arrayOf()` method. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.arrayOf; + +// Construct a string array +String[] manyWords = arrayOf("this", "is", "an", "example"); + +// Construct a double array +Double[] manyValues = arrayOf(1.0D, 2.0D, 3.0D); +``` + +## listOf + +Quickly construct an list of any type, equivalent to Kotlin's `mutableListOf()` method. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.listOf; + +// Construct a string list +List manyWords = listOf("this", "is", "an", "example"); + +// Construct a double list +List manyValues = listOf(1.0D, 2.0D, 3.0D); +``` + +## setOf + +Quickly construct an set of any type, equivalent to Kotlin's `mutableSetOf()` method. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.setOf; + +// Construct a string set +Set manyWords = setOf("this", "is", "an", "example"); + +// Construct a double set +Set manyValues = setOf(1.0D, 2.0D, 3.0D); +``` + +## mapOf + +Quickly construct an map of any type, equivalent to Kotlin's `mutableMapOf()` method. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.mapOf; +import static com.alibaba.testable.core.tool.CollectionTool.entryOf; + +// Construct a string to string map +Map manyWords = mapOf( + entryOf("language", "java"), + entryOf("type", "unittest"), + entryOf("library", "testable") +); + +// Construct a integer to double map +Map manyValues = mapOf( + entryOf(1, 10.12D), + entryOf(2, 20.24D), + entryOf(3, 30.36D) +); +``` + +## orderedMapOf + +Quickly construct ordered map (LinkedListMap) of any type. Compared with the HashMap map created by `mapOf()`, when traversing its keys or values in a loop, the order will always be the same as entries passed to `orderedMapOf()` method during construction. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.orderedMapOf; +import static com.alibaba.testable.core.tool.CollectionTool.entryOf; + +// Construct a string to string ordered map +Map manyWords = orderedMapOf( + entryOf("language", "java"), + entryOf("type", "unittest"), + entryOf("library", "testable") +); + +// Construct a integer to double ordered map +Map manyValues = orderedMapOf( + entryOf(1, 10.12D), + entryOf(2, 20.24D), + entryOf(3, 30.36D) +); +``` + +## entryOf + +Used with `mapOf()` and `orderedMapOf()` methods to construct a map. + +## slice + +Used to extract a part of data from any type of array to a new array. + +Usage example: + +```java +import static com.alibaba.testable.core.tool.CollectionTool.slice; +import static com.alibaba.testable.core.tool.CollectionTool.arrayOf; + +// Extract the elements of the specified string array from subscript 1 to 3 +// the returned new array content are ["is", "a", "simple"] +String[] fullWords = arrayOf("this", "is", "a", "simple", "example"); +String[] partOfWords = slice(fullWords, 1, 3); + +// If only given the index of starting position, all elements after this position are extracted +// the new array returned in the following example is [5, 8, 13, 21] +Integer[] fibonacci = arrayOf(1, 1, 2, 3, 5, 8, 13, 21); +Integer[] partOfFibonacci = slice(fibonacci, 4); +``` diff --git a/docs/en-us/doc/setup.md b/docs/en-us/doc/setup.md index 895f17c..e03bf5e 100644 --- a/docs/en-us/doc/setup.md +++ b/docs/en-us/doc/setup.md @@ -7,6 +7,7 @@ Use TestableMock - [Access private members of the class under test](en-us/doc/private-accessor.md): enable unit tests directly invoke or access private members of the class under test, solve the problems of private member initialization and private method testing - [Quickly construct complicated parameter object](en-us/doc/omni-constructor.md)：generate arbitrarily nested object instances, simplify their internal member assignment methods, solve the problem of long initialization codes for method parameters - [Assist test void method](en-us/doc/test-void-method.md): use the mock validator to check the internal logic of method, solve the problem that unit testing is difficult to implement to the method with no return value +- [Quickly create collection instances](en-us/doc/collection-tools.md): provide utility methods for collection creation, solve the problem of redundant codes during java test data preparation ## Use in Maven project diff --git a/docs/en-us/sidebar.md b/docs/en-us/sidebar.md index 712287e..0d177d8 100644 --- a/docs/en-us/sidebar.md +++ b/docs/en-us/sidebar.md @@ -4,6 +4,7 @@ - [Private Accessor](en-us/doc/private-accessor.md) - [Omni Constructor](en-us/doc/omni-constructor.md) - [Test Void Method](en-us/doc/test-void-method.md) + - [Collection Tools](en-us/doc/collection-tools.md) - Usage Guide - [Verify Mock Invocation](en-us/doc/invoke-matcher.md) diff --git a/docs/zh-cn/doc/annotations.md b/docs/zh-cn/doc/annotations.md index e5f9fb4..3480d3d 100644 --- a/docs/zh-cn/doc/annotations.md +++ b/docs/zh-cn/doc/annotations.md @@ -20,11 +20,14 @@ - 作用于：Mock容器类中的方法 -| 参数 | 类型 | 是否必须 | 默认值 | 作用 | -| --- | --- | --- | ---- | --- | -| targetClass | Class | 否 | N/A | 指定Mock目标的调用者类型 | -| targetMethod | String | 否 | N/A | 指定Mock目标的方法名 | -| scope | MockScope | 否 | MockScope.GLOBAL | 指定Mock的生效范围 | +| 参数 | 类型 | 是否必须 | 默认值 | 作用 | +| --- | --- | --- | ---- | --- | +| targetClass | Class | 否 | N/A | 指定Mock目标的调用者类型 | +| targetClassName | String | 否 | N/A | 与`targetClass`相同，主要用于无法直接引用的私有内部类 | +| targetMethod | String | 否 | N/A | 指定Mock目标的方法名 | +| scope | MockScope | 否 | MockScope.GLOBAL | 指定Mock的生效范围 | + +> 说明：`targetClass`和`targetClassName`参数不能同时使用 #### @MockNew diff --git a/docs/zh-cn/doc/collection-tools.md b/docs/zh-cn/doc/collection-tools.md new file mode 100644 index 0000000..e6f33a5 --- /dev/null +++ b/docs/zh-cn/doc/collection-tools.md @@ -0,0 +1,129 @@ +常用集合构建工具 +--- + +在编写测试数据的时候，经常会用到各种集合类型的对象，然而Java原生的集合类型需要反复调用`add()`或`put()`方法来添加数据，使代码显得十分冗长。 + +`TestableMock`借鉴了Kotlin语言简洁的集合构造方法，提供了一个实用的集合构造工具类`CollectionTool`，让Java集合对象的创建从此变得优雅。 + +这个工具类提供了以下全局静态方法： + +## arrayOf + +快速构造任意类型的数组，等效于Kotlin的`arrayOf()`方法。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.arrayOf; + +// 构造一个字符串数组 +String[] manyWords = arrayOf("this", "is", "an", "example"); + +// 构造一个浮点值数组 +Double[] manyValues = arrayOf(1.0D, 2.0D, 3.0D); +``` + +## listOf + +快速构造任意类型的列表，等效于Kotlin的`mutableListOf()`方法。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.listOf; + +// 构造一个字符串列表 +List manyWords = listOf("this", "is", "an", "example"); + +// 构造一个浮点值列表 +List manyValues = listOf(1.0D, 2.0D, 3.0D); +``` + +## setOf + +快速构造任意类型的集合，等效于Kotlin的`mutableSetOf()`方法。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.setOf; + +// 构造一个字符串集合 +Set manyWords = setOf("this", "is", "an", "example"); + +// 构造一个浮点值集合 +Set manyValues = setOf(1.0D, 2.0D, 3.0D); +``` + +## mapOf + +快速构造任意类型的无序映射表，等效于Kotlin的`mutableMapOf()`方法。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.mapOf; +import static com.alibaba.testable.core.tool.CollectionTool.entryOf; + +// 构造一个字符串到字符串的映射 +Map manyWords = mapOf( + entryOf("language", "java"), + entryOf("type", "unittest"), + entryOf("library", "testable") +); + +// 构造一个整型数值到浮点数值的映射 +Map manyValues = mapOf( + entryOf(1, 10.12D), + entryOf(2, 20.24D), + entryOf(3, 30.36D) +); +``` + +## orderedMapOf + +快速构造任意类型的有序映射表（LinkedListMap），相较于`mapOf()`创建的HashMap对象，当在循环中遍历它的键或值列表时，其访问顺序始终会与构造时传给`orderedMapOf()`方法的数据顺序一致。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.orderedMapOf; +import static com.alibaba.testable.core.tool.CollectionTool.entryOf; + +// 构造一个字符串到字符串的有序映射 +Map manyWords = orderedMapOf( + entryOf("language", "java"), + entryOf("type", "unittest"), + entryOf("library", "testable") +); + +// 构造一个整型数值到浮点数值的有序映射 +Map manyValues = orderedMapOf( + entryOf(1, 10.12D), + entryOf(2, 20.24D), + entryOf(3, 30.36D) +); +``` + +## entryOf + +配合`mapOf()`和`orderedMapOf()`方法使用，用于构造映射表。 + +## slice + +用于提取任意类型数组中间的一部分数据，组成新的数组。 + +用法示例： + +```java +import static com.alibaba.testable.core.tool.CollectionTool.slice; +import static com.alibaba.testable.core.tool.CollectionTool.arrayOf; + +// 提取指定字符串数组从下标1到3之间的元素，得到的新数组内容为["is", "a", "simple"] +String[] fullWords = arrayOf("this", "is", "a", "simple", "example"); +String[] partOfWords = slice(fullWords, 1, 3); + +// 只传入起始位置下标，提取该位置之后的所有元素，下例返回的新数组内容为[5, 8, 13, 21] +Integer[] fibonacci = arrayOf(1, 1, 2, 3, 5, 8, 13, 21); +Integer[] partOfFibonacci = slice(fibonacci, 4); +``` diff --git a/docs/zh-cn/doc/setup.md b/docs/zh-cn/doc/setup.md index e2ab7c8..eeacddf 100644 --- a/docs/zh-cn/doc/setup.md +++ b/docs/zh-cn/doc/setup.md @@ -7,6 +7,7 @@ - [访问被测类私有成员](zh-cn/doc/private-accessor.md)：使单元测试能直接调用和访问被测类的私有成员，解决私有成员初始化和私有方法测试的问题 - [快速构造参数对象](zh-cn/doc/omni-constructor.md)：生成任意复杂嵌套的对象实例，并简化其内部成员赋值方式，解决被测方法参数初始化代码冗长的问题 - [辅助测试void方法](zh-cn/doc/test-void-method.md)：利用Mock校验器对方法的内部逻辑进行检查，解决无返回值方法难以实施单元测试的问题 +- [快速构造集合对象](zh-cn/doc/collection-tools.md)：提供简洁易用的集合构造和常用操作方法，解决准备测试数据时Java集合初始化代码冗长的问题 ## 在Maven项目中使用 diff --git a/docs/zh-cn/sidebar.md b/docs/zh-cn/sidebar.md index b973ab3..81dafcc 100644 --- a/docs/zh-cn/sidebar.md +++ b/docs/zh-cn/sidebar.md @@ -4,6 +4,7 @@ - [直接访问私有成员](zh-cn/doc/private-accessor.md) - [快速构造复杂入参](zh-cn/doc/omni-constructor.md) - [测试无返回值的方法](zh-cn/doc/test-void-method.md) + - [常用集合构建工具](zh-cn/doc/collection-tools.md) - 使用指南 - [校验Mock调用](zh-cn/doc/invoke-matcher.md)