UE4 template for c++ project with test environment
Launch your tests and code coverage with just 1 commandline + get nice reports!
/!\ For now it works only on Window
- 1. Why?
- 2. Requirements
- 3. Step by step guide
- 4. Debug
- 5. Formatting
- 6. Other scripts
- 7. What does it look like?
- 8. Contributing and Supporting
1. Why?
My first needs were to:
- improve my process of proof concepting
- try to reduce the UE4 tests build duration
- ensure quality to avoid regressions by running tests frequently
Then after reading this great series of articles, testing and guiding by its author @ericlemes:
- https://ericlemes.com/2018/12/12/unit-tests-in-unreal-pt-1/
- https://ericlemes.com/2018/12/13/unit-tests-in-unreal-pt-2/
- https://ericlemes.com/2018/12/17/unit-tests-in-unreal-pt-3/
this project came to life!
2. Requirements
- PowerShell
- Unreal Engine
- UE4-GoogleTest (but it is embeded as a gitmodule)
- OpenCppCoverage
- NodeJs v12.16.1 use NVM for windows
- Pm2
3. Step by step guide
3.1. Clone to a specific dir
git clone git@github.com:NansPellicari/UE4-TPL-CppWithTestEnv.git MyNewGame
# /!\ renaming destination folder is important, because UE4 doesn't like dash in project name
cd MyNewGame
3.2. Rename the project files
.\ChangeProjectName.bat 'MyNewGame'
# and respond "y" in every prompt
# or
.\ChangeProjectName.bat -f 'MyNewGame'
# to avoid prompts
# or
.\ChangeProjectName.bat -f 'MyPreviousGameName' 'MyNewGame'
# if you've already change the name but you decide to change again
This will:
- clean all unnecessary files and folders (if exists: Binaries, Saved, ...)
- prompt you to set the UE4 root path
- rename all
MyProject
files & folders - change all
MyProject
occurences in./Source/
,./Config/
and./TestsReports/
directories. - generate Project Files (for VS or VScode)
3.3. Get submodules
This repo embeds UE4-GoogleTest plugins which is a UE4 plugin, a simple bridge for the googletest project.
git submodule init
git submodule update --init --recursive
3.4. Test
Run all tests to check if all is well configure.
.\RunTests.bat -b gg
# this one failed intentionally
.\RunTests.bat -b ue4 MyNewGame
# last parameter is recommended for this one (see section 3.4.1.),
# otherwise it launches every UE4 tests
Each run will build using the UE4 builder.
gg
: a program build,ue4
: an editor build.
It means that the first time they are launch, they'll take time to build.
But on next runs you'll see how fast they are, it is such a pleasureβΊοΈ
Special winner is thegg
buildπ
For the both builds ( ue4
or gg
), you can filter tests to run.
3.4.1. Filter for UE4 build
For this build it is really important to filter, otherwise it will run all Unreal Engine's tests, which is A LOT!
You can add any filters you need as if:
.\RunTests.bat -b ue4 MyNewGame MyPlugin.Core
this will call
UE4Editor-Cmd.exe
with this parameter-ExecCmds=" mation RunTests MyNewGame+MyPlugin. Core; quit"
3.4.2. Filters for GG build
Use params as google test defined.
.\RunTests.bat -c -b gg --gtest_filter=FirstTest.*-FirstTest.ShouldTestFalse
to list test names:
.\RunTests.bat -b gg --gtest_list_tests
3.5. Coverage
Just add -c
option:
.\RunTests.bat -c -b gg
.\RunTests.bat -c -b ue4 MyNewGame
3.6. Go to your Dashboard
I use node and pm2 to create a simple server which display all tests reports and coverages in one dashboard.
Find it at http://localhost:9999/
to see last results in a glimpse.
Each block is a link to the more detailed reports page (see section What does it look like? below).
3.7. Reinstall git + git modules on your new git repository
rd .\git\
rd .\Plugins\GoogleTest
git init
git submodule add git@github.com:NansPellicari/UE4-GoogleTest.git Plugins/GoogleTest
git add .
git ci -m "Initial my UE4 project with GoogleTest + OpenCppCoverage"
git remote add origin git@github.com:MY_USER/MY_REPO.git
git push origin master
or my preferred choice, just change the remote repository (thanks to this gist):
git remote rm origin
git remote add origin git@github.com:MY_USER/MY_REPO.git
git config master.remote origin
git config master.merge refs/heads/master
3.8. Shutdown server
Don't forget to shutdown server when you don't use it or if you switch to other project.
cd TestsReports/
npm run server:stop
# or to ensure to kill every server
npm run server:clean
# or
pm2 delete all
4. Debug
4.1. In VScode
When you run the script
.\GenerateProjectFiles.bat
it merge the data from.vscode/tasks.sample.json
&.vscode/launch.sample.json
to their respective generated config file. So if you want to add some defaults settings add them to the.vscode/*.sample.json
files (they are versioned too).
First add a build conf in .vscode/tasks.json
:
{
"label": "GoogleApp Win64 Development Build",
"group": "build",
"command": "Engine\\Build\\BatchFiles\\Build.bat",
"args": [
"GoogleTestApp",
"Win64",
"Development",
"<YourProjectPath>\\GoogleTestApp.uproject",
"-waitmutex"
],
"problemMatcher": "$msCompile",
"type": "shell",
"options": {
"cwd": "<yourUE4Path>"
}
}
and debug configs in your .vscode/launch.js
:
{
"version": "0.2.0",
"configurations": [
// ...
{
"name": "GoogleApp (Development)",
"request": "launch",
"preLaunchTask": "GoogleApp Win[64 or 32] Development Build",
"program": "<YourProjectPath>\\Binaries\\Win[64 or 32]\\GoogleTestApp.exe",
"args": [],
"cwd": "<yourUE4Path>",
"stopAtEntry": false,
"externalConsole": true,
"type": "cppvsdbg",
"visualizerFile": "<yourUE4Path>\\Engine\\Extras\\VisualStudioDebugging\\UE4.natvis"
}
]
}
4.2. VS (Visual Studio)
WIP
5. Formatting
5.1. VS Code
The same as in Debug section, you can run the script
.\GenerateProjectFiles.bat
and.vscode/settings.sample.json
will be merged to.vscode/settings.json
file.
To format on save and during edition, add this in your .vscode/settings.json
:
{
"editor.formatOnSave": true,
"editor.formatOnType": true
}
To make the formatter (I use prettier) recognize the json format for .uproject
and .plugin
files (but It should be placed on the user or workspace settings.json
, see this):
{
"files.associations": {
"_.uproject": "json",
"_.uplugin": "json"
}
}
5.2. VS
WIP
6. Other scripts
A bunch of scripts can be used to help you during your development session:
Script | Usage |
---|---|
.\GeneratePlugins.bat |
Copies files from the c++ Blank Project template in the Unreal Engine directory and rename it |
.\Clean.bat |
Removes all generated files and folder |
.\GenerateProjectFiles.bat |
- Uses Clean.bat - Uses <ue4 rootpath>Engine\Binaries\DotNET\UnrealBuildTool.exe to generate VS or VSCode files from the .uproject file- Download npm dependencies in the TestsReports folder + clean and start nodejs report's server - Merge .vscode/*.sample.json > generated .vscode/*.json files |
.\Scripts\RenameFileAndContent.ps1 |
(powershell file) In a given directory, change recursively files, folder, contents, from and to given names, usages:.\Scripts\RenameFileAndContent.ps1 .\Plugins\Dir\ AClassNameIWantToChange TheNewClassName |
7. What does it look like?
7.1. Google Test App reports
I choose to use Xunit viewer because (at the age of this repo creation):
- it is actively maintain
- is the most advanced UI on npm
7.2. Google Test App Coverage
7.3. UE4 reports
7.4. UE4 Coverage
8. Contributing and Supporting
I've decided to make all the code I developed for my games free to use and open source.
I am a true believer in the mindset that sharing and collaborating makes the world a better place.
I'll be very glad if you decided to help me to follow my dream.
How? | With |
---|---|
Donating Because I'm an independant developer/creator and for now I don't have any income, I need money to support my daily needs (coffeeeeee). |
|
Contributing You are very welcome if you want to contribute. I explain here in details what is the most comfortable way to me you can contribute. |
CONTRIBUTING.md |