Troubleshooting

This guide covers common issues and their solutions.

Test Discovery Issues

Tests Not Found

Symptom: No tests are discovered by the JUnit runner.

Common Causes:

Missing @IncludeEngines("berrycrush") annotation
Incorrect scenario file paths
Scenario files not on the classpath

Solution:

Ensure your test class has the correct annotations:

@IncludeEngines("berrycrush")
@BerryCrushScenarios(locations = "scenarios/pets.scenario")
class PetApiTest

Verify scenario files are in src/test/resources/.

Scenario Files Not Loaded

Symptom: Test class is discovered but scenarios show as “0 tests”.

Solution:

Check the file extension is .scenario
Verify the path in locations is relative to the resources folder
Ensure the file contains valid scenario syntax

// Correct
@BerryCrushScenarios(locations = "scenarios/pets.scenario")

// Also correct - multiple files
@BerryCrushScenarios(locations = [
    "scenarios/pets.scenario",
    "scenarios/users.scenario"
])

Configuration Issues

Bindings Not Found

Symptom: IllegalStateException: Cannot instantiate bindings class

Solution:

Ensure your bindings class has a public no-arg constructor:

// ✓ Correct
class MyBindings : BerryCrushBindings {
    override fun getBindings() = mapOf("key" to "value")
}

// ✗ Wrong - requires constructor argument
class MyBindings(private val config: Config) : BerryCrushBindings {
    override fun getBindings() = mapOf("key" to config.value)
}

For dependency injection, use the Spring module:

@Component
class MyBindings(
    @Autowired private val config: Config
) : BerryCrushBindings

OpenAPI Spec Not Found

Symptom: FileNotFoundException when loading OpenAPI spec

Solution:

Ensure the spec file is on the classpath:

src/test/resources/
└── petstore.yaml

And reference it correctly using @BerryCrushSpec:

@BerryCrushSpec(paths = ["petstore.yaml"])  // Relative to resources root
@BerryCrushConfiguration(bindings = MyBindings::class)

HTTP Request Issues

Connection Refused

Symptom: ConnectException: Connection refused

Solution:

Ensure the API server is running
Verify the baseUrl in getBindings() is correct
Check for firewall/network issues

class MyBindings : BerryCrushBindings {
    override fun getBindings() = mapOf(
        "default" to OpenApiSpecValue("api.yaml", "http://localhost:8080")  // Must match server port
    )
}

Timeout Errors

Symptom: Requests timeout

Solution:

Increase timeout in configuration:

@BerryCrushConfiguration(
    timeout = 60_000L  // 60 seconds
)

SSL/TLS Errors

Symptom: SSLHandshakeException or certificate errors

Solution:

For development/testing with self-signed certificates:

class MyBindings : BerryCrushBindings {
    override fun configure(config: Configuration) {
        config.sslValidation = false  // Disable for testing only
    }
}

Warning

Never disable SSL validation in production.

Assertion Failures

JSONPath Not Matching

Symptom: JSONPath assertions fail unexpectedly

Debug Steps:

Print the actual response body
Verify the JSONPath expression
Check data types (string vs number)

scenario: Debug response
  when: I request pets
    call ^listPets
  then: I check the response
    assert status 200
    assert $.name equals "Fluffy"

Schema Validation Fails

Symptom: SchemaValidationException

Solution:

Compare the actual response against the OpenAPI schema
Check for optional vs required fields
Verify data types match

// Get detailed validation errors
@BerryCrushConfiguration(
    pluginClasses = [SchemaValidationPlugin::class]
)

Spring Integration Issues

Bindings Not Injected

Symptom: Spring dependencies are null

Solution:

Ensure you’re using the Spring module and annotations:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@IncludeEngines("berrycrush")
@BerryCrushScenarios(locations = "scenarios/pets.scenario")
class PetApiTest  // Make sure Spring context is initialized

Context Not Available

Symptom: NoSuchBeanDefinitionException

Solution:

Check that the Spring module is included:

dependencies {
    testImplementation("org.berrycrush.berrycrush:spring:0.1.0")
}

Plugin Issues

Plugin Not Executing

Symptom: Plugin callbacks are not called

Causes:

Plugin not registered
Exception during plugin initialization
Priority conflicts

Solution:

Add logging to debug:

class DebugPlugin : BerryCrushPlugin {
    override val name = "debug"
    override val priority = 1000  // High priority, runs first

    override fun onScenarioStart(context: ScenarioContext) {
        println("Debug: Starting ${context.name}")
    }
}

Report Not Generated

Symptom: Report file is empty or missing

Solution:

Check the output path is writable
Verify the plugin is registered
Ensure tests actually ran

@BerryCrushConfiguration(
    plugins = ["report:json:build/reports/test.json"]
)

Understanding Error Messages

BerryCrush provides detailed error context to help diagnose test failures quickly.

HTTP Execution Errors

When HTTP requests fail, exceptions include rich context:

HTTP request failed: POST https://api.example.com/pets
Cause: Connection timeout

--- Scenario Context ---
Scenario: Create Pet
File: src/test/resources/pets.scenario
Step: Create a new pet (line 15)
Operation: createPet

--- Request ---
POST https://api.example.com/pets
  Content-Type: application/json
  Authorization: [MASKED]

Request Body:
{"name": "Fluffy", "type": "cat"}

--- Response ---
Status: 500 Internal Server Error
Duration: 150ms
  Content-Type: application/json

Response Body:
{"error": "Database connection failed"}

Sensitive headers like Authorization, Cookie, and X-Api-Key are automatically masked in error output.

Assertion Failures

Assertion exceptions show expected vs actual values clearly:

Assertion failed for $.name [jsonpath]
  Expected: "Fluffy"
  Actual:   "Buddy"

Scenario: Verify Pet Name
Step: Check pet details (line 25)
Operation: getPetById

Response Status: 200 OK
Response Body (preview): {"id": 123, "name": "Buddy", ...}

Schema Validation Errors

Schema validation failures include the failing path and response context:

Schema validation failed at path: #/components/schemas/Pet:
  - required property 'name' is missing
  - property 'age' must be integer

Scenario: Create Pet
Operation: createPet

Response Status: 200
Response (preview): {"id": 123, "type": "cat"}

Parse Errors

Parse exceptions show surrounding source context:

Parse error in test.scenario at line 3, column 8: Unknown step type 'invlid'

     1: Scenario: Test
     2:   Given a user
>    3:   When invlid step
     4:   Then success
     5: End Scenario
            ^

Configuring Error Context

Control error output through configuration:

configuration {
    // Include/exclude body content in errors
    errorContext.includeRequestBody = true
    errorContext.includeResponseBody = true

    // Limit body size (prevents huge payloads in logs)
    errorContext.maxBodySize = 4096  // bytes

    // Additional headers to mask (case-insensitive)
    // Default: authorization, cookie, set-cookie, x-api-key, x-auth-token
}

Or via parameters:

@BerryCrushConfiguration(
    parameters = [
        "errorContext.maxBodySize=1024",
        "errorContext.includeResponseBody=false"
    ]
)

Getting Help

If your issue isn’t listed here:

Check the GitHub Issues for similar problems
Enable debug logging: -Dberrycrush.debug=true
Create a minimal reproducing example
Open a new issue with: - BerryCrush version - Kotlin/Java version - Error message and stack trace - Sample code to reproduce