Manual build setup
CircleCI is designed to set up most tests automatically because we infer your settings from your code. However, if you have an unusual setup or work in a framework that has no idiomatic way to set up your project, you’ll need to set it up manually. Fortunately, this is a pretty straightforward procedure. If you follow this guide, you should be running your tests in 20 minutes or less.
Standard projects not inferred
Before we get into the details of a manual setup, here is a quick fix to a common problem first-timers can experience.
If you have a standard project and received a “no test” status, it is probably because the project is in a subdirectory.
This is easy to fix: add a file named
circle.yml on the project repo pointing to build directory and
CircleCI will run your tests from that subdirectory. For example, to set the build directory to
sub-directory, you can use the following
general: build_dir: api
The circle.yml file
From here, we’ll assume that you’re manually setting up your tests.
The first thing to do is to add an empty
circle.yml file to the root
directory of your repository. We recommend adding this upfront on a branch to
keep you and your colleagues on the same page.
We have provided a
full reference for the
but you won’t need that for now—
we’ll guide you through a simple setup and you can check out the comprehensive docs later.
The anatomy of a CircleCI build
For testing purposes, most applications and libraries require five to six standard phases that are run sequentially:
- Configure the test machine
- Check out your code
- Set up your test dependencies
- Set up your test databases
- Run your tests
- (Optionally) deploy your code
Each phase consists of a list of bash commands.
Normally, these commands are inferred by CircleCI, but if you are reading this, you will likely be manually adding some commands to the
You can modify which—and in what order—commands are run by adding
post when needed.
Take a look at the aforementioned reference guide
should you want to learn more details.
Failing commands (those with a non-zero exit code) will cause the whole build to fail, and you’ll receive a notification.
Configuring your test machine
For the most part, there is nothing that you have to add to configure the test machine. We have already installed the most common libraries, languages, browsers, and databases that you’ll need. See Ubuntu 12.04 and Ubuntu 14.04 build image pages for a comprehensive list of what we have installed. If you need anything else installed, please contact us and CircleCI support should be able to accommodate you. Be aware that for security reasons, we don’t provide root access.
The machine section
circle.yml file is the place where you can tweak common settings, such as timezone, language version used, and
Checking out code
CircleCI will check out your code from your GitHub repository. Currently, we don’t check out submodules. If your project requires that, add the appropriate commands.
checkout: post: - git submodule sync - git submodule update --init
If you have any files in your repositories that need to be moved, now is a good time. Here is an example of how to do that.
checkout: post: - cp ./ci-server/config.yml ./app-server/config.yml
Setting up your dependencies
In all likelihood, you’ll have a list of libraries and dependencies that your app requires.
CircleCI automatically detects Ruby’s Gemfile, Python’s requirements.txt, Clojure’s project.clj, and Node’s package.json, and then runs the appropriate commands to install the dependencies.
CircleCI also supports PHP’s Composer.
When needed, you can modify which dependencies-related commands are run using
dependencies: post: - python ./install-packages
Setting up your test databases
At this point, you’ll want to create your database, load it with your schema, and (possibly) preload it with data.
If you use MySQL or Postgres, you can use the
database and the
ubuntu user rather than creating the database yourself.
No password is required for any database.
database: override: - mysql -u ubuntu circle_test < my-database-setup.sql
Running your tests
Now that everything is prepared, add your test commands to the
circle.yml file so that you can run your tests.
test: override: - php ./test-suite/run.php --unit-tests
Depending on the structure of your tests, you may need to start your application server first.
test: override: - php ./app/run-server.php --daemon - php ./test-suite/run.php --unit-tests
You should be good to go. Happy testing!
If your tests fail and you need to fix something, CircleCI has a list of common problems and their solutions that can help you debug many issues. You might also like to know that we allow you to SSH in during your builds. This lets you check out how CircleCI works and facilitates nimble and efficient debugging.