Skip to main content

Migrate an existing codebase to use Batect

Every codebase is unique, and there is no one "right" way to use Batect. However, based on our experience migrating existing codebases to use Batect, we've collected some advice that may be helpful as you migrate your own codebase:

Start small, work incrementally

There's no need to convert your entire development lifecycle over to use Batect in one go. This could be quite time consuming, and means that you won't see the benefit of Batect until you complete the process.

Instead, we highly recommend you work incrementally. Exactly what "incrementally" means for you will depend on your codebase.

As an example, for a stereotypical backend application with a database and a dependency on some external services, incrementally migrating to Batect might follow these steps:

  1. Establish a build environment in Batect that can be used to compile the application
  2. Expand the build environment to support running unit tests, linters and other tools
  3. Establish test environments, starting with integration tests1, and working one dependency at a time
  4. Work through each dependency until all integration tests are running in Batect
  5. Repeat for other, higher-level tests like end-to-end tests
  6. Use the containers and configuration you've created as part of the above steps to run your application locally

Learn from others

We've collected lessons learnt from using Batect with a variety of tools and ecosystems in the using Batect with other tools and ecosystems section of the documentation.

There's also a huge number of sample projects that you can use as examples for your own projects.

Ask the community

If you need help or run into a problem, don't be afraid to ask for help. You can open an issue on GitHub or start a discussion.


  1. Everyone uses different terms for different kinds of tests. When we use the phrase integration test here, we're referring to tests that test the interaction between a component of your application and an external dependency like a database or service. Ham Vocke's The Practical Test Pyramid explains this kind of testing in detail.

Subscribe to the Batect newsletter

Get news and announcements direct to your inbox.