Quick Start

This guide will help you get BerryCrush up and running quickly.

Prerequisites

Java 21 or later
Kotlin 2.0+ (for Kotlin DSL)
Gradle 8.0+ or Maven 3.9+
An OpenAPI specification for your API

Installation

Gradle (Kotlin DSL)

Add the following to your build.gradle.kts:

dependencies {
    testImplementation("org.berrycrush.berrycrush:core:0.1.0")
    testImplementation("org.berrycrush.berrycrush:junit:0.1.0")

    // For Spring Boot projects
    testImplementation("org.berrycrush.berrycrush:spring:0.1.0")
}

Maven

Add the following to your pom.xml:

<dependencies>
    <dependency>
        <groupId>org.berrycrush.berrycrush</groupId>
        <artifactId>core</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.berrycrush.berrycrush</groupId>
        <artifactId>junit</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Creating Your First Test

1. Create an OpenAPI specification

Place your OpenAPI spec in src/test/resources/petstore.yaml:

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /api/pets:
    get:
      operationId: listPets
      responses:
        '200':
          description: List of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

2. Create a scenario file

Create src/test/resources/scenarios/pet-api.scenario:

scenario: List all pets
  when: I request the pets list
    call ^listPets
  then: I receive a list of pets
    assert status 200
    assert $.pets notEmpty

3. Create bindings

Create a bindings class to provide configuration:

class PetStoreBindings : BerryCrushBindings {
    override fun getBindings(): Map<String, Any> {
        return mapOf(
            "baseUrl" to "http://localhost:8080"
        )
    }

    override fun getOpenApiSpec(): String? {
        return "petstore.yaml"
    }
}

4. Create a test class

Create your JUnit 5 test class:

import org.berrycrush.berrycrush.junit.*
import org.junit.platform.suite.api.IncludeEngines

@IncludeEngines("berrycrush")
@BerryCrushScenarios(locations = "scenarios/pet-api.scenario")
@BerryCrushConfiguration(bindings = PetStoreBindings::class)
class PetApiTest

5. Run the test

Run your test using Gradle:

./gradlew test

You should see output indicating which scenarios passed or failed.

Using Conditional Assertions

When an API can return different valid responses, use conditional assertions:

scenario: Create or update a pet
  when: I upsert a pet
    call ^updatePet
      petId: 123
      body:
        name: "Max"

    if status 201
      # Resource was created
      assert $.id notEmpty
    else if status 200
      # Resource was updated
      assert $.name equals "Max"
    else
      fail "Expected status 200 or 201"

Conditionals support checking status codes, JSON path values, and headers. See Scenario File Syntax for full syntax.

Next Steps

Learn about Custom Steps to create reusable step definitions
Explore Plugins to extend functionality
Check out Reporting for test report generation
See Tutorial for a complete walkthrough