Sbt Integration Tests: The New Way

Oct 31, 2025 by Admin 35 views

Hey everyone! So, if you're deep into the Scala world and use sbt for your builds, you've probably noticed some changes happening. The guys over at eed3si9n.com recently dropped some news about the deprecation of custom configurations in sbt. Now, I know what you're thinking: "What about my integration tests?" It's a super valid question, especially since the IntegrationTest configuration was a go-to for so many of us. Well, fret not! This article is all about diving deep into the recommended way to set up integration tests in sbt after this shift. We'll break down why the old way isn't the way anymore and, more importantly, show you the shiny, new, and arguably better approach. So grab your favorite beverage, get comfy, and let's unravel the mystery of sbt integration tests together!

Why the Change? Understanding the Deprecation of Custom Configs

Alright guys, let's get down to the nitty-gritty of why this change even happened. For the longest time, sbt allowed us to define custom configurations, and IntegrationTest was, in essence, one of those custom configurations that became a de facto standard for many projects. The idea was simple: have a separate configuration for running your integration tests, distinct from your regular unit tests. This isolation was crucial. It meant you could manage dependencies differently, run tests in a separate JVM, and generally keep your build process cleaner. However, the sbt maintainers, led by the brilliant minds behind its development, realized that while functional, custom configurations added a layer of complexity that wasn't always necessary and could lead to confusion. The article you linked, which is a fantastic resource, really highlights that IntegrationTest specifically didn't offer much beyond what other mechanisms could provide. It essentially became a special case that was harder to maintain and understand for new users. The goal of sbt is to be powerful yet accessible. By streamlining the configuration system and deprecating these less-than-essential custom configs, they're aiming to make sbt more intuitive. This doesn't mean integration tests are going away – far from it! It just means we need to adapt our setup to leverage sbt's core features more effectively. Think of it like upgrading your toolkit; some old tools get retired, but the new ones often do the job better and are easier to use once you get the hang of them. So, when we talk about the deprecation of custom configs, especially IntegrationTest, we're talking about a move towards a more unified and robust sbt experience. It's about simplifying the build definition so that it's more maintainable and less prone to obscure errors. This transition might seem a bit daunting at first, but trust me, the end result is a cleaner, more efficient build process that everyone, from seasoned sbt veterans to newcomers, can appreciate. The key takeaway here is that sbt is evolving, and this change is a part of that evolution, pushing towards a more streamlined and user-friendly build tool.

The Old Way vs. The New Way: A Sneak Peek

Before we dive headfirst into the how, let's briefly touch on the contrast between the old and new approaches. In the old way, you'd typically see something like this in your build.sbt: you'd define a new configuration, say IntegrationTest, extending Test, and then explicitly configure its settings, like testFrameworks, fork, and scalacOptions. This often involved a bit of boilerplate, making your build.sbt file grow longer and, frankly, a bit more complex than it needed to be. You might have also had separate dependency scopes for your integration tests. The problem with this, as we touched upon, is that IntegrationTest was a custom configuration that, while useful, wasn't a first-class citizen in the same way as Compile or Test. It introduced a special case that required specific handling. Now, with the deprecation, we're moving towards a more integrated approach. The recommended way to set up integration tests in sbt leverages the existing Test configuration but uses different mechanisms to achieve the same isolation and control. Instead of defining a whole new configuration, we're talking about using different test groups or scopes within the Test configuration itself. This means your integration tests will still run in their own environment, potentially in a separate forked JVM, and with their own set of dependencies, but all managed under the umbrella of the Test configuration. It's like reorganizing your closet; instead of buying a whole new wardrobe for your formal, you're just using dividers and boxes within your existing closet to keep things tidy and separate. This approach reduces the need for custom configuration definitions, making your build.sbt cleaner and more aligned with sbt's core principles. It simplifies the overall build structure, making it easier to read, write, and maintain. So, the fundamental shift is from creating new configurations to cleverly utilizing and extending the existing Test configuration. This might sound like a subtle change, but it has significant implications for how we structure our projects and manage our tests. We're essentially making integration tests a more first-class part of the standard testing setup, rather than an add-on. This is a move towards a more pragmatic and maintainable build configuration, which is always a win in my book, guys!

The Modern Approach: Leveraging Test Groups and Scopes

Okay, so how do we actually do this modern approach, right? The core idea is to use sbt's built-in capabilities to differentiate between your unit tests and your integration tests within the existing Test configuration. The most common and recommended way to achieve this is by using test groups. You can assign different groups to your test classes, and then sbt allows you to selectively run tests based on these groups. This is a game-changer, folks! It means you don't need a separate IntegrationTest configuration anymore. Instead, you can have your unit tests and integration tests live side-by-side, each tagged with their respective groups. To implement this, you'll typically modify your build.sbt file. You'll need to define your test groups and then configure sbt to run them. Let's say you want to group your tests into Unit and Integration. You would add something like this to your build.sbt:

// Define test groups
Test / testGrouping := (Test / testGrouping).value.map { tg =>
  import sbt.testing.Tests.Group
  
  val unitTests = new Group("Unit", _.endsWith("Spec"), subTasks = Seq.empty)
  val integrationTests = new Group("Integration", _.endsWith("IntegrationSpec"), subTasks = Seq.empty)
  
  tg.withNewGroup(unitTests).withNewGroup(integrationTests)
}

// Optional: Specify which tests to run by default if you don't want all tests to run
// For example, to only run unit tests by default:
// Test / testFrameworks := List(new TestFramework("org.scalatest.tools.Framework")) // if using scalatest
// Test / run := (Test / run).toTask("").dependsOn(Test / testFrameworks.taskValue)

// To fork integration tests (recommended for isolation):
IntegrationTest / fork := true
IntegrationTest / javaOptions ++= Seq("-Dconfig.resource=application-test.conf") // Example: loading specific config

Here's the breakdown:

Test / testGrouping: This is where the magic happens. We're telling sbt how to group our tests. We define two Groups: Unit and Integration. The first argument is the group name, and the second is a predicate that determines which test classes belong to that group. Here, I've used simple naming conventions (.endsWith("Spec") for unit tests and .endsWith("IntegrationSpec") for integration tests). You can, of course, adjust these predicates to match your project's naming strategy. The subTasks part is usually empty unless you have more granular control needed.
Running Specific Groups: Once grouped, you can run tests using the testOnly command with the group name. For example, sbt "testOnly Unit" will run only your unit tests, and sbt "testOnly Integration" will run only your integration tests. This provides the isolation we're looking for without needing a new configuration.
Forking JVMs: For true isolation, especially with integration tests that might have resource-intensive setups or potential side effects, you'll want to fork a new JVM. The example shows IntegrationTest / fork := true. This is crucial. By default, sbt might run all tests in the same JVM, which can lead to conflicts or interference between tests. Forking ensures each test run (or group of tests, depending on configuration) starts with a clean slate.
Custom Configurations for Forking: You might notice the IntegrationTest / fork := true. This syntax might seem familiar, and that's because sbt still allows defining scoped settings for specific tasks or configurations, even if IntegrationTest as a standalone configuration is deprecated. The key is that we're not defining a new configuration but rather scoping settings to a conceptual name that aligns with how we want to run our tests. So, IntegrationTest / fork := true applies the fork setting specifically when you're targeting what you've conceptually called IntegrationTest tests (via testOnly Integration). This is a powerful way to apply specific JVM options or configurations just for your integration test runs.

This approach keeps your build.sbt cleaner, more readable, and leverages sbt's features in a way that's intended for modern usage. It's all about smart organization within the existing structure.

Setting Up Dependencies for Integration Tests

Now, let's talk about dependencies, because this is another area where the old custom configuration approach often required specific tweaks. When you had a separate IntegrationTest configuration, you could easily declare dependencies that were only needed for integration tests. With the new approach, where we're using test groups within the Test configuration, we still need a way to manage these specific dependencies. Thankfully, sbt provides a clean way to handle this using configurations. While we're moving away from defining custom configurations like IntegrationTest, sbt still has built-in configurations like Test and Compile. We can leverage these to manage dependencies effectively. The key is to use the Compile and Test configurations appropriately and understand how they interact.

Here’s how you typically manage dependencies for your integration tests in this new paradigm:

Core Project Dependencies: These are your regular application dependencies that are available in both Compile and Test. You declare these in the standard way:
```
libraryDependencies ++= Seq(
  "com.example" %% "my-library" % "1.0.0",
  // ... other core dependencies
)
```
Unit Test Dependencies: These are dependencies needed only for your unit tests (e.g., testing frameworks like ScalaTest, Specs2, or mocking libraries like Mockito).
```
libraryDependencies ++= Seq(
  "org.scalatest" %% "scalatest" % "3.2.15" % Test,
  "org.mockito" %% "mockito-scala" % "1.17.29" % Test
  // ... other unit test dependencies
)
```
The % Test part is crucial here. It tells sbt that these libraries should only be available when running tests (i.e., within the Test configuration).
Integration Test Dependencies: Now, for the dependencies specifically required for your integration tests (e.g., database drivers, HTTP clients for integration, test containers, custom assertion libraries), you'll also declare them with the % Test scope. The critical difference is how you run them. Because you're using test groups (testOnly Integration), sbt ensures that these dependencies are available only when the integration tests are executing, thanks to the grouping mechanism we discussed earlier. You don't need a separate configuration; the test grouping handles the conditional availability.
```
libraryDependencies ++= Seq(
  // Example: PostgreSQL driver for integration tests
  "org.postgresql" % "postgresql" % "42.6.0" % Test,
  // Example: Testcontainers for managing external resources
  "org.testcontainers" % "testcontainers" % "1.19.3" % Test,
  "org.testcontainers" %% "postgresql" % "1.19.3" % Test,
  // ... other integration test dependencies
)
```
The key insight here is that the distinction between unit test dependencies and integration test dependencies is managed by how you run the tests (using testOnly Unit vs. testOnly Integration) and which classes are included in those runs, rather than by separate sbt configurations. All these dependencies are declared under the Test configuration scope. Sbt is smart enough to make them available only when the corresponding test group is activated. This simplifies your build.sbt significantly, as you're not managing multiple configuration blocks for dependencies. You declare all test-related dependencies under Test, and then use test grouping and potentially task-specific settings (like IntegrationTest / fork := true) to control their execution environment.

Running Your Integration Tests Effectively

So, you've set up your test groups, you've managed your dependencies – now, how do you actually run these integration tests? This is where the testOnly command comes into play, and it's super powerful when combined with the test grouping strategy we've discussed. Instead of relying on a specific IntegrationTest task, you'll use testOnly along with the group name you defined in your build.sbt.

Let's recap the commands:

To run only unit tests:
```
sbt "testOnly Unit"
```
This command tells sbt to execute all test classes that belong to the Unit group. Remember, the Unit group was defined using a predicate in Test / testGrouping in our build.sbt, likely matching classes ending in Spec.
To run only integration tests:
```
sbt "testOnly Integration"
```
This is the command that replaces the old it:test or IntegrationTest/test pattern. It will execute only the tests belonging to the Integration group, typically matching classes ending in IntegrationSpec.
To run all tests (unit and integration):
```
sbt test
```
If you run the plain sbt test command, sbt will execute all tests across all defined test groups by default. This is great for a full test suite run.

Important Considerations for Running Integration Tests:

Forking JVMs: As we've emphasized, for integration tests, it's highly recommended to run them in a separate JVM. This prevents state leakage between tests and ensures a clean environment. You achieve this by setting IntegrationTest / fork := true in your build.sbt. When you then run sbt "testOnly Integration", sbt will honor this setting and fork a new JVM specifically for these tests.
Configuration Files: Integration tests often rely on specific configuration files (e.g., database connection strings, external service URLs). You can ensure these are loaded correctly by using JVM system properties or environment variables. For instance, in your build.sbt, you might set IntegrationTest / javaOptions += "-Dconfig.resource=application-integration.conf". This tells the Typesafe Config library (or similar) to load a specific configuration file when the integration tests are running in their forked JVM.
Test Databases and Services: If your integration tests require a running database or other external services, consider using tools like Testcontainers. Testcontainers allows you to spin up Docker containers for databases, message queues, etc., on the fly, manage their lifecycle, and connect your tests to them. This keeps your test environment consistent and reproducible.
Execution Order: While sbt tries to run tests efficiently, be mindful of the order if certain tests have dependencies on each other. However, for robust integration tests, it's generally better to design them to be independent. If you must enforce an order, sbt provides mechanisms, but it can add complexity.

By using testOnly with your defined test groups and ensuring appropriate settings like forking and configuration loading, you gain precise control over your integration test execution. This modern approach is more flexible, easier to manage, and aligns better with sbt's evolving design philosophy.

Best Practices and Tips for Success

Alright guys, we've covered the what, the why, and the how. Now, let's wrap up with some best practices and handy tips to make sure your integration test setup in sbt is as smooth and effective as possible. Following these guidelines will help you avoid common pitfalls and maintain a healthy, robust testing suite.

1. Keep Integration Tests Independent

This is a golden rule in testing, but it's especially critical for integration tests. Each integration test should be able to run on its own, without depending on the outcome or state left behind by another test. This means:

Set up all necessary resources (database connections, mocked services, files) at the beginning of each test or test suite.
Clean up resources thoroughly after each test or test suite.
Avoid global state that can be modified by tests.

Why is this so important? Because when you run integration tests in a forked JVM, each run is a fresh start. If your tests rely on each other, failures can cascade, making it incredibly hard to pinpoint the root cause. Independence makes your tests reliable and your debugging process much saner.

2. Use Testcontainers for External Dependencies

If your integration tests need databases, message brokers, or other external services, Testcontainers is your best friend. It allows you to define and manage these dependencies using Docker containers. This ensures that your integration tests run in an environment that closely mirrors production, without requiring you to manually set up and manage these services.

Reproducibility: Ensures consistent environments across developer machines and CI/CD pipelines.
Isolation: Each test run can have its own instance of a service.
Cleanliness: Containers are automatically started and stopped.

This dramatically simplifies the setup and teardown process for your integration test environment.

3. Configure JVM Options Wisely

As mentioned, forking the JVM for integration tests is crucial for isolation. However, you might also need to tweak JVM options for performance or to load specific configurations.

Memory: If your integration tests are memory-intensive, you might need to increase the heap size: IntegrationTest / javaOptions += "-Xmx4g".
System Properties: Load configuration files, set feature flags, or provide other parameters via system properties: IntegrationTest / javaOptions += "-Dmy.setting=value".

Be judicious with these settings; only change them if necessary. Over-optimization can sometimes introduce complexity.

4. Structure Your Test Code Clearly

Even though we're using test groups within the Test configuration, it's still a good idea to have a clear directory structure for your tests. Typically, you might have:

src/test/scala/com/example/unittests/ for your unit tests.
src/test/scala/com/example/integrationtests/ for your integration tests.

This makes it easy to visually distinguish between the two types of tests and helps ensure your naming conventions (used in testGrouping) are easy to maintain.

5. Leverage `sbt-ci-release` or Similar Plugins for CI/CD

When integrating with CI/CD pipelines, ensure your pipeline is configured to run the correct set of tests. You might want to run unit tests on every commit but only run integration tests on specific branches or before a release. Plugins like sbt-ci-release can help manage the release process, including test execution.

6. Keep `build.sbt` Clean and Readable

With the move away from custom configurations, your build.sbt should become simpler.

Use clear variable names for your test group predicates.
Comment sections that might be unclear.
Avoid excessive boilerplate.

The goal is to make your build definition understandable at a glance. The new approach helps achieve this by aligning more closely with sbt's core design.

By incorporating these best practices, you'll be well on your way to setting up and maintaining an efficient and reliable integration test suite in sbt. It's all about smart organization, leveraging the right tools, and adhering to sound testing principles. Happy testing, guys!