Migration Guide

This guide helps you migrate from other API testing tools to BerryCrush.

From Cucumber

BerryCrush’s scenario syntax is simpler and more API-focused than Gherkin.

Feature Files

Cucumber:

# features/pets.feature
Feature: Pet API
  Scenario: List pets
    Given the API is available
    When I send a GET request to "/pets"
    Then the response status should be 200

BerryCrush:

# scenarios/pets.scenario
scenario: List pets
  when: I request pets
    call ^listPets
  then: I get a response
    assert status 200

Key differences:

File extension is .scenario (not .feature)
No Feature: block needed (use feature: for grouping if desired)
Uses call ^operationId instead of raw HTTP requests
Built-in assertions (assert status, assert $.path, etc.)
Variable binding syntax uses {{variableName}}

Step Definitions

Cucumber (Java):

@Given("the API is available")
public void theApiIsAvailable() {
    baseUrl = "http://localhost:8080";
}

@When("I send a GET request to {string}")
public void sendGet(String path) {
    response = RestAssured.get(baseUrl + path);
}

BerryCrush (Kotlin):

@Step("the API is available at {string}")
fun setBaseUrl(url: String, context: StepContext) {
    context.configuration.baseUrl = url
}

@Step("I request {word} {any}")
fun makeRequest(method: String, path: String, context: StepContext) {
    context.request(method, path)
}

Configuration:

Cucumber:

@CucumberOptions(
    features = "classpath:features",
    glue = "com.example.steps"
)

BerryCrush:

@BerryCrushScenarios(locations = "scenarios/pets.scenario")
@BerryCrushConfiguration(
    stepPackages = ["com.example.steps"]
)

From REST Assured

REST Assured tests can be converted to BerryCrush scenarios.

REST Assured:

@Test
public void testListPets() {
    given()
        .baseUri("http://localhost:8080")
        .header("Accept", "application/json")
    .when()
        .get("/api/pets")
    .then()
        .statusCode(200)
        .body("$.size()", greaterThan(0))
        .body("[0].name", notNullValue());
}

BerryCrush:

scenario: List pets
  when: I request pets
    call ^listPets
      header_Accept: "application/json"
  then: pets are returned
    assert status 200
    assert $.length() greaterThan 0
    assert $[0].name notEmpty

Benefits:

Readable by non-technical team members
Scenarios serve as documentation
OpenAPI validation included
Operations referenced by operationId

From Karate

Karate and BerryCrush share similar goals, with different syntax approaches.

Karate:

Feature: Pet API
  Background:
    * url 'http://localhost:8080'

  Scenario: List pets
    Given path '/api/pets'
    When method get
    Then status 200
    And match response == '#array'

BerryCrush:

feature: Pet API
  background:
    given: API is ready
      call ^health
      assert status 200

  scenario: List pets
    when: I request pets
      call ^listPets
    then: pets are returned
      assert status 200
      assert $.pets notEmpty

Key differences:

BerryCrush uses call ^operationId instead of raw paths
OpenAPI integration for automatic request/response validation
JUnit 5 native (no custom runner needed)
Conditional assertions with if/else/fail

Migration Checklist

Before Migration

☐ Document existing test coverage
☐ Identify custom step definitions
☐ Export OpenAPI specification
☐ Inventory test data and fixtures

During Migration

☐ Set up BerryCrush dependencies
☐ Convert feature files to scenario files
☐ Migrate step definitions
☐ Configure bindings
☐ Set up CI/CD reports

After Migration

☐ Verify all tests pass
☐ Compare coverage before/after
☐ Update CI/CD configuration
☐ Train team on new syntax

Getting Help

If you encounter issues during migration:

Check Troubleshooting for common problems
Review the Tutorial for complete examples
Open an issue on GitHub for specific questions