CPM.cmake/test/integration/tutorial.md

Integration Test Tutorial

Let's create an integration test which checks that CPM.cmake can make a specific package available.

First we do some boilerplate.

require_relative './lib'

class MyTest < IntegrationTest
  # test that CPM.cmake can make https://github.com/cpm-cmake/testpack-adder/ available as a package
  def test_make_adder_available
  end
end

Now we have our test case class, and the single test method that we will require. Let's focus on the method's contents. The integration test framework provides us with a helper class, Project, which can be used for this scenario. A project has an assoiciated pair of source and binary directories in the temporary directory and it provides methods to work with them.

We start by creating the project:

prj = make_project

make_project is method of IntegrationTest which generates a source and a binary directory for it based on the name of our test class and test method. The project doesn't contain anything yet, so let's create some source files:

prj.create_file 'main.cpp', <<~SRC
  #include <iostream>
  #include <adder/adder.hpp>
  int main() {
      std::cout << adder::add(1, 2) << '\\n';
      return 0;
  }
SRC
prj.create_file 'CMakeLists.txt', <<~SRC
  cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
  project(using-adder)
  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
  include("%{cpm_path}")
  CPMAddPackage("gh:cpm-cmake/testpack-adder@1.0.0")
  add_executable(using-adder main.cpp)
  target_link_libraries(using-adder adder)
SRC

Note the line include("%{cpm_path}") when creating CMakeLists.txt. It contains a markup %{cpm_path}. Project#create_file will see such markups and substitute them with the appropriate values (in this case the path to CPM.cmake).

Now that we have the two files we need it's time we configure our project. We can use the opportunity to assert that the configure is successful as we expect it to be.

assert_success prj.configure

Now we can read the generated CMakeCache.txt and assert that certain values we expect are inside. Project provides a method for that: read_cache. It will return an instance of Project::CMakeCache which contains the data from the cache and provides additional helper functionalities. One of them is packages, which is a hash of the CPM.cmake packages in the cache with their versions, binary, source directories. So let's get the cache and assert that there is only one CPM.cmake package inside ant it has the version we expect.

cache = prj.read_cache
assert_equal 1, cache.packages.size
assert_equal '1.0.0', cache.packages['testpack-adder'].ver

Finally let's assert that the project can be built. This would mean that CPM.cmake has made the package available to our test project and that it has the appropriate include directories and link libraries to make an executable out of main.cpp.

assert_success prj.build

You can see the entire code for this tutorial in tutorial.rb in this directory.