diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-code-coverage.mdx b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-code-coverage.mdx new file mode 100644 index 00000000..9354eba9 --- /dev/null +++ b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-code-coverage.mdx @@ -0,0 +1,135 @@ +--- +title: Code Coverage +--- + +import { Steps, Tabs, TabItem } from "@astrojs/starlight/components"; + +Code coverage provides a convenient way to see what parts of SplashKit are being tested. This is +helpful for checking that existing tests are adequate, as well as for locating parts of the code +would be good candidates for new tests. Consider generating a code coverage report after adding a +new test, to see if there are any parts of the code that aren't being executed. This can sometimes +help you come up with new test cases. + +## Pre-requisites + +To generate code coverage reports, install the required program based on your platform: + + + + Install lcov via your package manager e.g., `apt install lcov` (note that your Linux + distribution may use a different package manager rather than `apt`, and you may need to `sudo` + this command) + + Install gcovr via homebrew: `brew install gcovr` + + Code coverage is currently not supported on Windows with MSYS. Please use WSL if you're a + Windows user. + + + +## Generating code coverage + +### From the command line + + + + + +1. Change to the cmake project directory + `cd ./projects/cmake` +2. Select the coverage configuration preset + `cmake --preset LinuxCoverage` +3. Build the unit test executable + `cmake --build build/ --target skunit_tests` +4. Capture initial coverage + `cmake --build build/ --target lcov-init-coverage` +5. Run the test executable + `../../bin/skunit_tests` +6. Capture test coverage + `cmake --build build/ --target lcov-capture-coverage` +7. Generate a coverage report in HTML format + `genhtml -o coverage-report/ build/lcov.info` +8. Open `index.html` to view the report + ![LCOV report](images/code-coverage/lcov-report.png) + + + + + + +1. Change to the cmake project directory + `cd ./projects/cmake` +2. Select the coverage configuration preset + `cmake --preset macOSCoverage` +3. Build the unit test executable + `cmake --build build/ --target skunit_tests` +4. Run the test executable + `../../bin/skunit_tests` +5. Capture test coverage and generate a report in HTML format + `gcovr --root ../.. --filter ".*/coresdk/src/.*" --html-nested coverage-report/coverage.html` +6. Open `coverage.html` to view the report + ![Gcovr report](images/code-coverage/gcovr-report.png) + + + + + +Code coverage is currently not supported on Windows with MSYS. Please use WSL if you're a Windows +user. + + + + +### In VS Code + +Note that currently code coverage reports won't display properly with versions of the CMake Tools +extension 1.21.36 and beyond. To work around this, you can install an older version of the extension +by clicking the arrow next to Install/Uninstall (depending on if you have CMake Tools installed +already) and selecting "Install Specific Version...". The latest version known to work is 1.20.53. + + + + + +1. Go to the CMake Tools settings in VS Code, switch to the Workspace tab, and change the following + settings: + **Coverage Info Files:** + Click Add Item and add `${workspaceFolder}/projects/cmake/build/lcov.info` + ![Coverage Info Files](images/code-coverage/option-coverage-info.png) + **Pre Run Coverage Target:** `lcov-init-coverage` + ![Lcov Pre Run Coverage Target](images/code-coverage/option-pre-run-lcov.png) + **Post Run Coverage Target:** `lcov-capture-coverage` + ![Lcov Post Run Coverage Target](images/code-coverage/option-post-run-lcov.png) + +2. Rebuild the test project, then run tests with coverage with this button + ![Run Tests with Coverage](images/code-coverage/button-run-coverage.png) +3. After the tests run, the test explorer pane in VS Code should update with the coverage info: + ![Coverage Info](images/code-coverage/result-test-explorer.png) + + + + + + +1. Go to the CMake Tools settings in VS Code, switch to the Workspace tab, and change the following + settings: + **Coverage Info Files:** + Click Add Item and add `${workspaceFolder}/projects/cmake/build/lcov.info` + ![Coverage Info Files](images/code-coverage/option-coverage-info.png) + **Post Run Coverage Target:** `gcovr-capture-coverage` + ![Gcovr Post Run Coverage Target](images/code-coverage/option-post-run-gcovr.png) + +2. Rebuild the test project, then run tests with coverage with this button + ![Run Tests with Coverage](images/code-coverage/button-run-coverage.png) +3. After the tests run, the test explorer pane in VS Code should update with the coverage info: + ![Coverage Info](images/code-coverage/result-test-explorer.png) + + + + + +Code coverage is currently not supported on Windows with MSYS. Please use WSL if you're a Windows +user. + + + diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/button-run-coverage.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/button-run-coverage.png new file mode 100644 index 00000000..15092f23 Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/button-run-coverage.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/gcovr-report.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/gcovr-report.png new file mode 100644 index 00000000..5cace298 Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/gcovr-report.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/lcov-report.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/lcov-report.png new file mode 100644 index 00000000..c6f1b643 Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/lcov-report.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-coverage-info.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-coverage-info.png new file mode 100644 index 00000000..a1862bfa Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-coverage-info.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-gcovr.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-gcovr.png new file mode 100644 index 00000000..5cc55d8e Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-gcovr.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-lcov.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-lcov.png new file mode 100644 index 00000000..f6919b81 Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-post-run-lcov.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-pre-run-lcov.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-pre-run-lcov.png new file mode 100644 index 00000000..a3deba7a Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/option-pre-run-lcov.png differ diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/result-test-explorer.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/result-test-explorer.png new file mode 100644 index 00000000..3448147d Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/code-coverage/result-test-explorer.png differ