0
# Apache Flink Table Test Utils
1

2
A comprehensive test utilities library for Apache Flink's Table API and SQL ecosystem. This library provides fluent assertion APIs that simplify validation of table processing results, supporting both internal RowData structures and external Row representations with automatic type conversion capabilities.
3

4
## Package Information
5

6
- **Package Name**: flink-table-test-utils
7
- **Package Type**: Maven
8
- **Group ID**: org.apache.flink
9
- **Artifact ID**: flink-table-test-utils
10
- **Language**: Java
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>org.apache.flink</groupId>
15
    <artifactId>flink-table-test-utils</artifactId>
16
    <version>2.1.0</version>
17
    <scope>test</scope>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
import static org.apache.flink.table.test.TableAssertions.*;
25
```
26

27
For specific assertion types:
28

29
```java
30
import org.apache.flink.table.test.RowDataAssert;
31
import org.apache.flink.table.test.RowAssert;
32
import org.apache.flink.table.test.ArrayDataAssert;
33
import org.apache.flink.table.test.MapDataAssert;
34
import org.apache.flink.table.test.StringDataAssert;
35
import org.apache.flink.table.test.RowDataListAssert;
36
import org.apache.flink.table.test.DataTypeAssert;
37
import org.apache.flink.table.test.LogicalTypeAssert;
38
import org.apache.flink.table.test.lookup.cache.LookupCacheAssert;
39
```
40

41
## Basic Usage
42

43
```java
44
import static org.apache.flink.table.test.TableAssertions.*;
45
import org.apache.flink.table.data.RowData;
46
import org.apache.flink.table.types.DataType;
47
import org.apache.flink.types.RowKind;
48

49
// Assert on RowData
50
RowData rowData = /* ... */;
51
assertThat(rowData)
52
    .hasKind(RowKind.INSERT)
53
    .hasArity(3)
54
    .isNotNullAt(0);
55

56
// Assert on collections with type conversion
57
List<RowData> rows = /* ... */;
58
DataType dataType = /* ... */;
59
assertThatRows(rows)
60
    .asGeneric(dataType)
61
    .containsOnly(expectedRow);
62

63
// Assert on data types
64
assertThat(dataType)
65
    .isNullable()
66
    .hasLogicalType(expectedLogicalType);
67
```
68

69
## Architecture
70

71
The library is built around the `TableAssertions` entry point class that provides static factory methods for creating type-specific assertion objects. Each assertion class extends AssertJ's `AbstractAssert` to provide fluent assertion APIs:
72

73
- **Entry Point**: `TableAssertions` - Central factory for all assertion types
74
- **Data Assertions**: Specialized assertion classes for Flink's internal data structures
75
- **Type Assertions**: Utilities for validating Flink's type system
76
- **Conversion Utilities**: Automatic type conversion between internal and external representations
77

78
## Capabilities
79

80
### Main Entry Point
81

82
Entry point factory methods for creating assertions.
83

84
```java { .api }
85
public class TableAssertions {
86
    // External data structures
87
    public static RowAssert assertThat(Row row);
88
    
89
    // Internal data structures  
90
    public static RowDataAssert assertThat(RowData actual);
91
    public static ArrayDataAssert assertThat(ArrayData actual);
92
    public static MapDataAssert assertThat(MapData actual);
93
    public static StringDataAssert assertThat(StringData actual);
94
    
95
    // Collection assertions
96
    public static RowDataListAssert assertThatRows(Iterator<RowData> actual);
97
    public static RowDataListAssert assertThatRows(Iterable<RowData> actual);
98
    public static RowDataListAssert assertThatRows(Stream<RowData> actual);
99
    public static RowDataListAssert assertThatRows(RowData... rows);
100
    
101
    // Generic type assertions
102
    public static AbstractAssert<?, ?> assertThatGenericDataOfType(Object actual, LogicalType logicalType);
103
    public static AbstractAssert<?, ?> assertThatGenericDataOfType(Object actual, DataType dataType);
104
    
105
    // Type system assertions
106
    public static DataTypeAssert assertThat(DataType actual);
107
    public static LogicalTypeAssert assertThat(LogicalType actual);
108
}
109
```
110

111
### [Data Structure Assertions](./data-assertions.md)
112

113
Fluent assertions for Flink's internal data structures including RowData, ArrayData, MapData, and StringData with type conversion capabilities.
114

115
### [Type System Assertions](./type-assertions.md)
116

117
Comprehensive assertions for Flink's DataType and LogicalType system with validation of type properties, conversions, and hierarchies.
118

119
### [Collection Assertions](./collection-assertions.md)
120

121
Specialized assertions for collections of RowData with bulk operations and type-safe comparisons.
122

123
### [Lookup Cache Assertions](./lookup-cache-assertions.md)
124

125
Validation utilities for Flink's lookup cache functionality with key-value relationship testing.
126

127
## Types
128

129
### Core Types
130

131
```java { .api }
132
// From org.apache.flink.table.data
133
interface RowData extends Serializable {
134
    int getArity();
135
    RowKind getRowKind();
136
    boolean isNullAt(int pos);
137
}
138

139
interface ArrayData extends Serializable {
140
    int size();
141
    boolean isNullAt(int pos);
142
}
143

144
interface MapData extends Serializable {
145
    int size();
146
    ArrayData keyArray();
147
    ArrayData valueArray();
148
}
149

150
interface StringData extends Serializable {
151
    int numBytes();
152
    byte[] toBytes();
153
    String toString();
154
}
155
```
156

157
### External Types
158

159
```java { .api }
160
// From org.apache.flink.types
161
class Row implements Serializable {
162
    public Row(int arity);
163
    public int getArity();
164
    public RowKind getKind();
165
    public Object getField(int pos);
166
    public void setField(int pos, Object value);
167
}
168

169
enum RowKind {
170
    INSERT, UPDATE_BEFORE, UPDATE_AFTER, DELETE
171
}
172
```
173

174
### Type System Types
175

176
```java { .api }
177
// From org.apache.flink.table.types
178
class DataType implements Serializable {
179
    public LogicalType getLogicalType();
180
    public Class<?> getConversionClass();
181
    public List<DataType> getChildren();
182
    public DataType nullable();
183
    public DataType notNull();
184
}
185

186
// From org.apache.flink.table.types.logical
187
abstract class LogicalType implements Serializable {
188
    public boolean isNullable();
189
    public List<LogicalType> getChildren();
190
    public String asSummaryString();
191
    public boolean supportsInputConversion(Class<?> clazz);
192
    public boolean supportsOutputConversion(Class<?> clazz);
193
}
194
```
195

196
### Assertion Result Types
197

198
```java { .api }
199
// From org.assertj.core.api
200
abstract class AbstractAssert<SELF extends AbstractAssert<SELF, ACTUAL>, ACTUAL> {
201
    public SELF isEqualTo(Object expected);
202
    public SELF isNotEqualTo(Object expected);
203
    public SELF isNotNull();
204
    public SELF isNull();
205
}
206

207
class StringAssert extends AbstractAssert<StringAssert, String> {
208
    public StringAssert isEqualTo(String expected);
209
    public StringAssert contains(CharSequence... values);
210
    public StringAssert startsWith(String prefix);
211
}
212

213
class LongAssert extends AbstractAssert<LongAssert, Long> {
214
    public LongAssert isEqualTo(long expected);
215
    public LongAssert isGreaterThan(long other);
216
    public LongAssert isLessThan(long other);
217
}
218

219
class ListAssert<ELEMENT> extends AbstractAssert<ListAssert<ELEMENT>, List<? extends ELEMENT>> {
220
    public ListAssert<ELEMENT> containsOnly(ELEMENT... values);
221
    public ListAssert<ELEMENT> containsExactly(ELEMENT... values);
222
    public ListAssert<ELEMENT> hasSize(int expected);
223
}
224

225
class ByteArrayAssert extends AbstractAssert<ByteArrayAssert, byte[]> {
226
    public ByteArrayAssert hasSize(int expected);
227
    public ByteArrayAssert startsWith(byte... sequence);
228
    public ByteArrayAssert endsWith(byte... sequence);
229
}
230
```