tabletest

KO | EN

gitlite — search

#php #javascript #python #java #ios #library #linux #ruby #dotfiles #wordpress #jquery #azure

★ 30 Open GitHub ↗

Table-driven testing in JUnit with the readable and expressive TableTest format

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TableTest

TableTest extends JUnit for data-driven testing using a concise and readable table format. Express system behaviour through multiple examples, reducing test code while improving readability and maintainability.

```java

@TableTest("""
    Scenario                     | Example Years      | Is Leap Year?
    Not divisible by 4           | {1, 2001, 30001}   | No
    Divisible by 4               | {4, 2004, 30008}   | Yes
    Divisible by 100, not by 400 | {100, 2100, 30300} | No
    Divisible by 400             | {400, 2000, 30000} | Yes
    Year 0                       | 0                  | Yes
    Negative input               | -1                 | No
    """)
void testLeapYears(Year year, boolean isLeapYear) {
    assertEquals(isLeapYear, year.isLeap());
}

public static boolean parseBoolean(String input) {
    return input.equalsIgnoreCase("yes");
}
```

**Benefits:**

- **Readable**: Clear input/output relationships in structured tables
- **Maintainable**: Add test cases by adding table rows
- **Concise**: Eliminates repetitive test code
- **Self-documenting**: Tables serve as living documentation
- **Collaborative**: Non-technical stakeholders can understand and contribute

**Requirements**: Java 8+, JUnit 5.11+

**IDE Support**: Plugins for [IntelliJ](https://plugins.jetbrains.com/plugin/27334-tabletest) and [VS Code](https://marketplace.visualstudio.com/items?itemName=tabletest.tabletest) provide auto-formatting, syntax highlighting, and shortcuts for working with tables.

**Website**: [tabletest.org](https://tabletest.org) for documentation, tools overview, and more.

**Latest Updates**: See the [changelog](CHANGELOG.md) for details on recent releases and changes.

**User Guide**: See the [user guide](USERGUIDE.md) for more details on how to use TableTest.

## Table of Contents

- [Usage](#usage)
- [Value Formats](#value-formats)
- [Value Conversion](#value-conversion)
- [Additional Features](#additional-features)
- [Installation](#installation)
- [IDE Support](#ide-support)
- [Formatter](#formatter)
- [Reporter](#reporter)
- [Claude Code Plugin](#claude-code-plugin)
- [License](#license)

## Usage

Annotate test methods with `@TableTest` and provide table data as a text block (Java 15+), a string array (Java 8–14), a Kotlin raw string, or an [external file](#table-in-external-file).

Tables use pipes (`|`) to separate columns. The first row contains headers, the following rows contain test data. Each data row invokes the test method with cell values as arguments.

```java

@TableTest("""
    Scenario                              | Year | Is leap year?
    Years not divisible by 4              | 2001 | false
    Years divisible by 4                  | 2004 | true
    Years divisible by 100 but not by 400 | 2100 | false
    Years divisible by 400                | 2000 | true
    """)
public void leapYearCalculation(Year year, boolean expectedResult) {
    assertEquals(expectedResult, year.isLeap(), "Year " + year);
}
```

**Key points:**

- One parameter per data column (scenario column excluded)
- Parameters map by position, not name
- Values automatically convert to parameter types
- Test methods must be non-private, non-static, void return

Technically `@TableTest` is a [JUnit `@ParameterizedTest`](https://junit.org/junit5/docs/current/user-guide/index.html#writing-tests-parameterized-tests) with a custom-format argument source.

## Value Formats

The TableTest format supports four types of values:

- **Single values** specified with or without quotes (`abc`, `"a|b"`, `' '`)
- **Lists** of elements enclosed in brackets (`[1, 2, 3]`)
- **Sets** of elements enclosed in curly braces (`{a, b, c}`)
- **Maps** of key:value pairs enclosed in brackets (`[a: 1, b: 2]`). Keys can be quoted for special characters (`["key with spaces": value]`).

Lists, sets, and maps can be nested (`[a: [1, 2, 3], b: [4, 5, 6]]`).

```java

@TableTest("""
    Single value           | List        | Set               | Map
    Hello, world!          | [1, 2, 3]   | {1, 2, 3}         | [a: 1, b: 2, c: 3]
    'cat file.txt | wc -l' | [a, '|', b] | {[], [1], [1,2 ]} | [empty: {}, full: {1, 2, 3}]
    ""                     | []          | {}                | [:]
    """)
void testValues(String single, List<?> list, Set<?> set, Map<String, ?> map) {
    //...
}
```

## Value Conversion

TableTest converts table values to method parameter types using the following mechanisms (in order of priority):

1. **Custom type converter method** (in test class or in class referenced by `@TypeConverterSources`)
2. **Built-in conversion** (primitives, dates, enums, etc.)

### Custom Type Converter Methods

Custom type converter methods are `public static` methods in a `public class` annotated with `@TypeConverter`. The methods must accept exactly one parameter and return a value in the target type:

```java
@TypeConverter
public static LocalDate convertToDate(String input) {
    return switch (input) {
        case "today" -> LocalDate.now();
        case "tomorrow" -> LocalDate.now().plusDays(1);
        default -> LocalDate.parse(input);
    };
}
```

TableTest will search for a matching custom converter method in the test class, including inherited methods, and in any classes listed by a `@TypeConverterSources` annotation on the test class. The first custom converter with a return type matching the target type will be used.

TableTest is able to chain converters to transform a value to the target test method parameter type. Please see the [user guide](USERGUIDE.md) for more information about this powerful feature.

There is no specific naming pattern for custom converter methods, any method tagged with the `@TypeConverter` annotation fulfilling the requirements of a type converter will be considered. Only one type converter method per target type is possible per class.

### Built-In Conversion

TableTest falls back to [JUnit's built-in type converters](https://junit.org/junit5/docs/current/user-guide/index.html#writing-tests-parameterized-tests-argument-conversion-implicit) if no suitable custom converter method is found. This covers most standard Java types,

```java

@TableTest("""
    Number | Text | Date       | Class
    1      | abc  | 2025-01-20 | java.lang.Integer
    """)
void singleValues(short number, String text, LocalDate date, Class<?> type) {
    // test implementation
}
```

### Parameterized Types

TableTest will convert elements in compound values like List, Set, and Map to match parameterized types. Nested values are also traversed and converted. Map keys remain String type and are not converted. Both custom and build-in converters will be considered for conversion.

In the example below, the list of grades inside the map is converted to `List<Integer>`:

```java

@TableTest("""
    Grades                                       | Highest Grade?
    [Alice: [95, 87, 92], Bob: [78, 85, 90]]     | 95
    [Charlie: [98, 89, 91], David: [45, 60, 70]] | 98
    """)
void testParameterizedTypes(Map<String, List<Integer>> grades, int expectedHighestGrade) {
    // test implementation
}
```

### Array Parameters

List values also convert to array parameter types, including primitive arrays, nested arrays, and arrays of generic types:

```java

@TableTest("""
    Scenario   | Numbers   | Sum?
    Single     | [5]       | 5
    Multiple   | [1, 2, 3] | 6
    Empty      | []        | 0
    """)
void testIntArray(int[] numbers, int sum) {
    assertEquals(sum, Arrays.stream(numbers).sum());
}
```

### Null Values

Blank cells will translate to `null` for all parameter types except primitives. For primitives, it will cause an exception as they cannot represent a `null` value.

```java

@TableTest("""
    String | Integer | List | Map | Set
           |         |      |     |
    """)
void blankConvertsToNull(String string, Integer integer, List<?> list, Map<String, ?> map, Set<?> set) {
    assertNull(string);
    assertNull(integer);
    assertNull(list);
    assertNull(map);
    assertNull(set);
}
```

## Additional Features

TableTest contains a number of other useful features for expressing examples in a table format.

### Scenario Names

Add descriptive names to test rows by providing a scenario name in the first column:

```java

@TableTest("""
    Scenario     | Input | Output
    Basic case   | 1     | one
    Edge case    | 0     | zero
    """)
void test(int input, String output) {
    // test implementation
}
```

Scenario names make the tables better documentation and will be used as test display names. This makes the test failures more clear and debugging easier.

Optionally scenario names can be accessed in test methods by declaring it as a test method parameter tagged with annotation `@Scenario`.

### Value Sets

TableTest allows using a set in a single-value column to express that any of the listed values give the same result. This is a powerful feature that can be used to contract multiple rows that have identical expectations.

TableTest will create multiple test invocations for a row with a value set, one for each value in the set. The test method will be invoked 12 times, three times for each row, once for each value in the `Example years` set.

```java

@TableTest("""
    Scenario                              | Example years      | Is leap year?
    Years not divisible by 4              | {2001, 2002, 2003} | false
    Years divisible by 4                  | {2004, 2008, 2012} | true
    Years divisible by 100 but not by 400 | {2100, 2200, 2300} | false
    Years divisible by 400                | {2000, 2400, 2800} | true
    """)
public void testLeapYear(Year year, boolean expectedResult) {
    assertEquals(expectedResult, year.isLeap(), "Year " + year);
}
```

Scenario names will be augmented to include the value from the set being used for the current test invocation. This makes it easier to see which values caused problems in case of test failures.

Value sets can be used multiple times in the same row. TableTest will then perform a cartesian product, generating test invocations for all possible combinations of values. Use this judiciously, as the number of test cases grows multiplicatively with each additional set, as does the test execution time.

### Comments and Blank Lines

Lines starting with `//` (ignoring leading whitespace) are treated as comments and ignored. Comments allow adding explanations or temporarily disabling data rows.

Blank lines are also ignored and can be used to visually group related rows.

```java

@TableTest("""
    String         | Length?
    
    Hello world    | 11
    
    // The next row is currently disabled
    // "World, hello" | 12
    
    // Special characters must be quoted
    '|'            | 1
    '[:]'          | 3
    """)
void testComment(String string, int expectedLength) {
    assertEquals(expectedLength, string.length());
}
```

### Table in External File

Tables can be loaded from external files using the `resource` attribute. The file must be located as a resource relative to the test class. Typically, it is stored in the test `resources` directory or one of its subdirectories.

By default, the file is assumed to use UTF-8 encoding. If your file uses a different encoding, specify it with the `encoding` attribute.

```java

@TableTest(resource = "/external.table")
void testExternalTable(int a, int b, int sum) {
    assertEquals(sum, a + b);
}

@TableTest(resource = "/custom-encoding.table", encoding = "ISO-8859-1")
void testExternalTableWithCustomEncoding(String string, int expectedLength) {
    assertEquals(expectedLength, string.length());
}
```

### Publishing TableTest results

Functionality for publishing TableTest results to HTML, AsciiDoc, Markdown, or custom formats is available as the [Reporter](#reporter) tool.

## Installation

TableTest is available from [Maven Central Repository](https://central.sonatype.com/artifact/org.tabletest/tabletest-junit). Projects using Maven or Gradle build files can simply add TableTest as a test scope dependency alongside JUnit.

## Java and JUnit Compatibility

TableTest requires Java 8 or above and is compatible with JUnit 5.11 and above.

On Java 15+, use text blocks for table data (as shown in the examples above). On Java 8–14, pass table rows as a string array:

```java
@TableTest({
    "a | b | sum",
    "1 | 2 | 3",
    "4 | 5 | 9"
})
void testAddition(int a, int b, int sum) {
    assertEquals(sum, a + b);
}
```

Frameworks such as Quarkus and SpringBoot package their own version of JUnit. TableTest is compatible with Quarkus version 3.21.2 and above and SpringBoot version 3.4.0 and above. Please see the [compatibility tests](compatibility-tests) for examples of how to use TableTest with these frameworks.

### Compatibility Notes

Note that TableTest versions 0.5.4 - 0.5.7 needed JUnit 5.14 and above. JUnit 5.13.0 introduced breaking changes that broke compatibility with TableTest. This was fixed in JUnit 5.13.1.

**Upgrading from 1.0.0**: A clean rebuild is required — run `mvn clean test` or `gradle clean test` after changing the version. Running tests without a clean rebuild will fail with `AnnotationTypeMismatchException`. Kotlin projects are unaffected.

### Maven (pom.xml)

```xml

<dependencies>
    <dependency>
        <groupId>org.tabletest</groupId>
        <artifactId>tabletest-junit</artifactId>
        <version>1.2.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>6.1.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Gradle with Kotlin DSL (build.gradle.kts)

```kotlin
dependencies {
    testImplementation("org.tabletest:tabletest-junit:1.2.2")
    testImplementation("org.junit.jupiter:junit-jupiter:6.1.2")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
```

## IDE Support

### IntelliJ

The [TableTest plugin for IntelliJ](https://plugins.jetbrains.com/plugin/27334-tabletest) enhances your development experience when working with TableTest format tables. The plugin provides:

- Auto-formatting with `Cmd+Option+L` (macOS) / `Ctrl+Alt+L`
- Syntax highlighting for headers, delimiters, values, and comments
- Language injection — automatic TableTest support in `@TableTest` annotations

### VS Code

The [TableTest extension for VS Code](https://marketplace.visualstudio.com/items?itemName=tabletest.tabletest) provides equivalent support for Visual Studio Code:

- Auto-formatting via `Format Document` or the `TableTest: Format All Tables in Document` command
- Syntax highlighting for table content
- Language injection in Java and Kotlin files

## Formatter

The [TableTest Formatter](https://github.com/nchaugen/tabletest-formatter) provides consistent table layout across your codebase. It formats tables in Java files, Kotlin files, and standalone `.table` files.

- **Spotless plugin** — natively supported in Spotless Gradle 8.3.0+ and Maven 3.3.0+, no extra dependencies needed
- **CLI tool** — for standalone formatting or CI integration
- **EditorConfig support** — reads indent style and size from `.editorconfig`

The formatter returns input unchanged on parse errors, so it never breaks your build.

## Reporter

The [TableTest Reporter](https://github.com/nchaugen/tabletest-reporter) generates documentation from your TableTest tests. Run your tests, then run the reporter to turn test tables into readable HTML, AsciiDoc or Markdown output.

- **Gradle and Maven plugins** — integrates into your build
- **Pass/fail indicators** — rows are marked with test results in the generated output
- **Custom templates** — extend or replace built-in templates using Pebble

## Claude Code Plugin

Two guided skills for writing TableTest-style tests from inside [Claude Code](https://claude.ai/claude-code):

- **`/spec-by-example`** — clarify behaviour by working through concrete examples as a table
- **`/tabletest`** — create `@TableTest` methods with guided table design and a quality checklist

Install from the Claude Code CLI:

```shell
/plugin marketplace add https://tabletest.org/marketplace.json
/plugin install tabletest@tabletest.org
```

## License

TableTest is licensed under the liberal and business-friendly [Apache Licence, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) and is freely available on [GitHub](https://github.com/nchaugen/tabletest).

TableTest distributions prior to version 0.5.1 included the following modules from JUnit 5 released under [Eclipse Public License 2.0](https://raw.githubusercontent.com/junit-team/junit5/refs/heads/main/LICENSE.md):

- `org.junit.jupiter:junit-jupiter-params`
- `org.junit.platform:junit-platform-commons`

From version 0.5.1 onwards, these modules were no longer included in the `tabletest-junit` distribution.

TableTest binaries are published to the repositories of Maven Central. The artefacts signatures can be validated against [this PGP public key](https://keyserver.ubuntu.com/pks/lookup?search=nchaugen%40gmail.com).

tabletest

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README