tqcq/CPM.cmake
0
0
Fork 0
mirror of https://github.com/cpm-cmake/CPM.cmake.git synced 2025-11-22 04:07:49 -05:00
Code Issues Packages Projects Releases Wiki Activity

Split docs into multiple files. Complete tutorial. Reference.

Browse Source
This commit is contained in:
Borislav Stanimirov
2022-01-13 09:20:29 +02:00
parent c7fd76ae0e
commit 659e1a364d
5 changed files with 273 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
test/integration/README.md
View File

@@ -36,143 +36,8 @@ Writing tests makes use of the custom integration test framework in `lib.rb`. It
* In case there are multiple test methods, they will be executed in the order in which they are defined.
* The test methods should contain assertions which check for the expected state of things at varous points of the test's execution.
### More
### A simple tutorial
Let's create a test which checks that CPM.cmake can make a specific package available.
First we do some boilerplate.
```ruby
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:
```ruby
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:
```ruby
prj.create_file 'main.cpp', <<~SRC
#include <iostream>
#include <adder/adder.hpp>
int main() {
cout << adder::add(1, 2);
return 0;
}
```
### Notable Idiosyncrasies
As an integration test framework based on a unit test framework it suffers from several idiosyncrasies. Make sure you familiarize yourself with them before writing integration tests.
**No shared instance variables between methods**
The runner will create an instance of the test class for each test method. This means that instance variables defined in a test method, *will not* be visible in another. For example:
```ruby
class MyTest < IntegrationTest
def test_something
@x = 123
assert_equal 123, @x # Pass. @x is 123
end
def tese_something_else
assert_equal 123, @x # Fail! @x would be nil here
end
end
```
There are hacks around sharing Ruby state between methods, but we choose not to use them. If you want to initialize something for all test methods, use `setup`.
```ruby
class MyTest < IntegrationTest
def setup
@x = 123
end
def test_something
assert_equal 123, @x # Pass. @x is 123 thanks to setup
end
def tese_something_else
assert_equal 123, @x # Pass. @x is 123 thanks to setup
end
end
```
**`IntegrationTest` makes use of `Test::Unit::TestCase#cleanup`**
After each test method the `cleanup` method is called thanks to Test::Unit. If you require the use of `cleanup` in your own tests, make sure you call `super` to also run `IntegrationTest#cleanup`.
```ruby
class MyTest < IntegrationTest
def cleanup
super
my_cleanup
end
# ...
end
```
**Try to have assertions in test methods as opposed to helper methods**
Test::Unit will display a helpful message if an assertion has failed. It will also include the line of code in the test method which caused the failure. However if an assertion is not in the test method, it will display the line which calls the method in which it is. So, please try, to have most assertions in test methods (though we acknowledge that in certain cases this is not practical). For example, if you only require scopes, try using lambdas.
Instead of this:
```ruby
class MyTest < IntegrationTest
def test_something
do_a
do_b
do_c
end
def do_a
# ...
end
def do_b
# ...
assert false # will display failed line as "do_b"
end
def do_c
# ...
end
end
```
...write this:
```ruby
class MyTest < IntegrationTest
def test_something
do_a = -> {
# ...
}
do_b = -> {
# ...
assert false # will display failed line as "assert false"
}
do_c = -> {
# ...
}
do_a.()
do_b.()
do_c.()
end
end
```
* [A basic tutorial on writing integration tests.](tutorial.md)
* [A brief reference of the integration test framework](reference.md)
* Make sure you're familiar with the [idiosyncrasies](idiosyncrasies.md) of writing integration tests

98
test/integration/idiosyncrasies.md Normal file
View File

@@ -0,0 +1,98 @@
# Notable Idiosyncrasies When Writing Integration Tests
As an integration test framework based on a unit test framework the one created for CPM.cmake suffers from several idiosyncrasies. Make sure you familiarize yourself with them before writing integration tests.
## No shared instance variables between methods
The runner will create an instance of the test class for each test method. This means that instance variables defined in a test method, *will not* be visible in another. For example:
```ruby
class MyTest < IntegrationTest
def test_something
@x = 123
assert_equal 123, @x # Pass. @x is 123
end
def tese_something_else
assert_equal 123, @x # Fail! @x would be nil here
end
end
```
There are hacks around sharing Ruby state between methods, but we choose not to use them. If you want to initialize something for all test methods, use `setup`.
```ruby
class MyTest < IntegrationTest
def setup
@x = 123
end
def test_something
assert_equal 123, @x # Pass. @x is 123 thanks to setup
end
def tese_something_else
assert_equal 123, @x # Pass. @x is 123 thanks to setup
end
end
```
## `IntegrationTest` makes use of `Test::Unit::TestCase#cleanup`
After each test method the `cleanup` method is called thanks to Test::Unit. If you require the use of `cleanup` in your own tests, make sure you call `super` to also run `IntegrationTest#cleanup`.
```ruby
class MyTest < IntegrationTest
def cleanup
super
my_cleanup
end
# ...
end
```
## It's better to have assertions in test methods as opposed to helper methods
Test::Unit will display a helpful message if an assertion has failed. It will also include the line of code in the test method which caused the failure. However if an assertion is not in the test method, it will display the line which calls the method in which it is. So, please try, to have most assertions in test methods (though we acknowledge that in certain cases this is not practical). For example, if you only require scopes, try using lambdas.
Instead of this:
```ruby
class MyTest < IntegrationTest
def test_something
do_a
do_b
do_c
end
def do_a
# ...
end
def do_b
# ...
assert false # will display failed line as "do_b"
end
def do_c
# ...
end
end
```
...write this:
```ruby
class MyTest < IntegrationTest
def test_something
do_a = -> {
# ...
}
do_b = -> {
# ...
assert false # will display failed line as "assert false"
}
do_c = -> {
# ...
}
do_a.()
do_b.()
do_c.()
end
end
```

65
test/integration/reference.md Normal file
View File

@@ -0,0 +1,65 @@
# Integration Test Framework Refernce
## `TestLib`
A module for the framework. Provides global data and functionality. For ease of use the utility classes are *not* in this module.
Provides:
* `TMP_DIR` - the temporary directory for the current test run
* `CPM_PATH` - path to CPM.cmake. The thing that is being tested
* `TEMPLATES_DIR` - path to integration test templates
* `CPM_ENV` - an array of the names of all environment variables, which CPM.cmake may read
* `.clear_env` - a function to clear all aforementioned environment variables
## `Project`
A helper class to manage a CMake project.
Provides:
* `#initialize(src_dir, bin_dir)` - create a project with a given source and binary directory
* `#src_dir`, `#bin_dir` - get project directories
* `#create_file(target_path, text, args = {})` - create a file in the project's source directory with a given test. The `args` hash is used to interpolate markup in the text string.
* Will set `:cpm_path` in `args` to `TestLib::CPM_PATH` if not already present.
* If `:package` is present it will be added to the array `:packages`
* Will convert `:packages` form an array to a string
* `#create_file_from_template(target_path, source_path, args = {})` - create a file in the project source directory, based on another file in the project source directory. The contents of the file at `source_path` will be read and used in `create_file`
* `#create_lists_from_default_template(args = {})` - same as `create_file_from_template('CMakeLists.txt', 'lists.in.cmake', args)`
* `::CommandResult` - a struct of:
* `out` - the standard output from a command execution
* `err` - the standard error output from the execution
* `status` - the [`Process::Status`](https://ruby-doc.org/core-2.7.0/Process/Status.html) of the execution
* `#configure(extra_args = '') => CommandResult` - configure the project with optional extra args to CMake
* `#build(extra_args = '') => CommandResult` - build the project with optional extra args to CMake
* `::CMakeCache` - a helper class with the contents of a CMakeCache.txt. Provides:
* `::Entry` - a CMake cache entry of:
* `val` - the value as string
* `type` - the type as string
* `advanced?` - whether the entry is an advanced option
* `desc` - the description of the entry (can be an empty string)
* `::Package` - the CMake cache for a CPM.cmake package. A struct of:
* `ver` - the version as string
* `src_dir`, `bin_dir` - the source and binary directories of the package
* `.from_dir(dir)` - create an instance of `CMakeCache` from `<dir>/CMakeLists.txt`
* `#initialize(entries)` - create a cache from a hash of entries by name. Will populate packages.
* `#entries => {String => Entry}` - the entries of the cache
* `#packages => {String => Package}` - CPM.cmake packages by name found in the cache
* `#[](key) => String` - an entry value from an entry name. Created because the value is expected to be needed much more frequently than the entire entry data. To get a full entry use `cache.entries['name']`.
* `read_cache => CMakeCache` - reads the CMake cache in the binary directory of the project and returns it as a `CMakeCache` instance
## `IntegrationTest`
The class which must be a parent of all integration test case classes. It itself extends `Test::Unit::TestCase` with:
### Assertions
* `assert_success(res)` - assert that an instance of `Project::CommandResult` is a success
* `assert_same_path(a, b)` - assert that two strings represent the same path. For example on Windows `c:\foo` and `C:\Foo` do.
### Utils
* `cur_test_dir` - the directory of the current test case. A subdirectory of `TestLib::TMP_DIR`
* `make_project(template_dir = nil)` - create a project from a test method. Will create a the project's source and binary directories as subdirectories of `cur_test_dir`.
* Optionally work with a template directory, in which case it will copy the contents of the template directory (one from `templates`) in the project's source directory.

69
test/integration/tutorial.md Normal file
View File

@@ -0,0 +1,69 @@
# 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.
```ruby
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:
```ruby
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:
```ruby
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.
```ruby
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.
```ruby
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`.
```ruby
assert_success prj.build
```
You can see the entire code for this tutorial in [tutorial.rb](tutorial.rb) in this directory.

37
test/integration/tutorial.rb Normal file
View File

@@ -0,0 +1,37 @@
# This file is intentionally not prefixed with test_
# It is a tutorial for making integration tests and is not to be run from the runner
require_relative './lib'
class Tutorial < IntegrationTest
# test that CPM.cmake can make https://github.com/cpm-cmake/testpack-adder/ available as a package
def test_make_adder_available
prj = make_project
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
assert_success prj.configure
cache = prj.read_cache
assert_equal 1, cache.packages.size
assert_equal '1.0.0', cache.packages['testpack-adder'].ver
assert_success prj.build
end
end