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

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. The thing is: I'm fulltime dedicated to my project and these open source plugins, for coding I need a looooot of coffee, so please, help me to get my drug 😝 !!

• 1. Why?
• 2. Requirements
• 3. Step by step guide
  • 3.1. Clone to a specific dir
  • 3.2. Rename the project files
  • 3.3. Get submodules
  • 3.4. Test
    • 3.4.1. Filter for UE4 build
    • 3.4.2. Filters for GG build
  • 3.5. Coverage
  • 3.6. Go to your Dashboard
  • 3.7. Reinstall git + git modules on your new git repository
  • 3.8. Shutdown server
• 4. Debug
  • 4.1. In VScode
  • 4.2. VS (Visual Studio)
• 5. Formatting
  • 5.1. VS Code
  • 5.2. VS
• 6. Other scripts
• 7. What does it look like?
  • 7.1. Google Test App reports
  • 7.2. Google Test App Coverage
  • 7.3. UE4 reports
  • 7.4. UE4 Coverage
• 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 the gg 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

License Apache-2.0

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