Building & Running Unit Tests v3

• Building Tests
• New Protocols
• Github Issues

Testing was added into Version 3 to help guard against breaking changes mainly for the older protocols with little to no documentation available. At a minimum every protocol class (i.e. Source, Gamespy3, etc...) should have a set of tests including any new extensions of a protocol class such as Css and Minecraft. Most tests just include real server response data and the processed response. Adding a new test is pretty straight forward.

Building Tests

This example is for building tests for a game that extends an existing protocol such as Counter-Strike Source which extends the Source protocol. If you are creating a new protocol class from scratch please see New Protocols for more information.

1. You will need to make sure you have installed all the required development dependencies from composer so you are able to generate test data and run tests. composer install --optimize-autoloader --dev

2. You need to add a new protocol class to the tests folder with the same name as the protocol class you are wanting to test. The quickest way is to copy the ./tests/Protocols/Css.php file and rename it to match the protocol class you are testing. Note that all protocol classes and tests classes only have the first character capitalized and not camel case. This is due to how the protocol class is found when processing servers on case sensitive operating systems such as Linux (i.e. CentOS, Ubuntu, etc...).

   Example: You have a new protocol class called Myawesomegame and its file is ./src/GameQ/Protocols/Myawesomegame.php. cp ./tests/Protocols/Css.php ./tests/Protocols/Myawesomegame.php Do not forget to change the values in your new test file ./tests/Protocols/Myawesomegame.php especially the class name and the protocol value in the testResponses function. Failure to change the protocol value will cause the tests you are building to fail.

3. Next you need to generate some test data. There is a provided command line php script that will query passed server information and save it as a data set. To gather new data run php ./tests/Protocols/generate_provider -p myawesomegame -s <serverip:port>. The data from this command saved by the PHP script is stored under ./tests/Protocols/Providers/Myawesomegame/ as a raw server response and a json of the parsed response.

   Notes:

   1. When generating test data it is best to use publicly available servers and use the ip address of the server. Using domain names (i.e. someawesomeserver.com) will cause tests to fail in the future if the domain name no longer resolves to an IP address (i.e. server has closed and domain has expired). Real servers are never queried when tests are run however any domain names will still be resolved to their IP address when the server query is built. If the domain name can not be resolved the query build will fail causing the test to fail.
   2. It is a good idea to run a normal query on the server first to make sure it is responding properly and returning the data you want. Running the generate_provider script on a server that does not respond will save an empty response.
   3. It is best to generate multiple data settings using servers with many players, 0 players, different mods, etc... so that there is a good sample of tests in case there are any updates to server query protocols that change the response behavior.

4. Once you have your test data generated you can run the unit test for that specific test class using the following command ./vendor/bin/phpunit --filter 'GameQ\\Tests\\Protocols\\Myawesomegame' which will run PHPUnit for only that protocol class. It is best to use the filter when building new tests so you do not have to wait for the entire test suite to run to fix any issues with your tests. Once you are satisfied with your test it is a good idea to run the full unit test ./vendor/bin/phpunit before submitting your changes.

5. Once you have your tests built and passing check them for the PSR-2 code standard. The standard covers tests as well and if it does not pass the build will fail. You can check your test code with the following command: vendor/bin/phpcs src tests --extensions=php --ignore=bootstrap --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=build/config/phpcs.xml -v

6. Finally check your code with the PHP Mess Detector (PHPMD) to make sure you are not breaking any best practices. You can run the check with the following command: vendor/bin/phpmd src,tests xml build/config/phpmd.xml. This command will take a couple of minutes to run and does not provide any feedback until it is complete. If you have changes that are failing the PHPMD checks you can still create a pull request.

7. If everything looks good and passes create a new Pull Request. Your pull request will be tested so if it passes you are good to go. If it does not pass please make the necessary changes so that the tests pass.

New protocols

If you are adding a test for a new protocol class that does not extend an existing protocol you will need to add other tests such as checking the packets being sent out and any challenge parsing. A good place to start would be with the Source protocol test file at ./tests/Protocols/Source.php. Other tests maybe required as well depending on what the protocol class does. When you are comfortable with the tests please create a new Pull Request. Any required changes/fixes can be discussed there.

Issues

Tests for specific Github issues should be made using the issue number (i.e. Issue100.php) to assure the bug does not show back up at a later date due to another change. These tests should be added to the ./tests/Issues/ folder.