{"id":15722600,"url":"https://github.com/britzl/deftest","last_synced_at":"2025-05-07T02:28:55.631Z","repository":{"id":46584090,"uuid":"69938337","full_name":"britzl/deftest","owner":"britzl","description":"Unit testing in Defold","archived":false,"fork":false,"pushed_at":"2023-09-29T21:48:54.000Z","size":495,"stargazers_count":45,"open_issues_count":2,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-14T14:04:26.096Z","etag":null,"topics":["defold","defold-library","lua","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/britzl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-04T05:48:01.000Z","updated_at":"2024-11-25T19:10:56.000Z","dependencies_parsed_at":"2024-10-24T16:50:57.387Z","dependency_job_id":"e50f9a3f-3a1e-465d-bab8-c44ace53b213","html_url":"https://github.com/britzl/deftest","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdeftest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdeftest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdeftest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdeftest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/britzl","download_url":"https://codeload.github.com/britzl/deftest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246419808,"owners_count":20774157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library","lua","unit-testing"],"created_at":"2024-10-03T22:08:37.560Z","updated_at":"2025-03-31T23:31:01.118Z","avatar_url":"https://github.com/britzl.png","language":"Lua","readme":"![](logo.jpg)\n\n# DefTest\nUnit testing is a software development process in which the smallest testable parts of the code are individually and independently tested. The purpose is to verify an expected and defined behavior in one part of the code as another part of it is changed to guarantee that it still behaves as expected even after the change. Being able to catch unforeseen side effects (read: bugs) early reduces the effort and cost involved in fixing them. Unit tests can be run manually but it is more common to automate the process, typically when new code is added to a version control system such as Git. This process is also known as [Continuous Integration, or CI](https://www.wikiwand.com/en/Continuous_integration) since the local changes are integrated into a shared repository, often several times a day.\n\nThis project shows one way of running unit tests in Defold using the [Telescope](https://github.com/norman/telescope) unit testing framework. Telescope was chosen thanks to it's simplicity and clean code. A couple of other popular unit testing frameworks are:\n\n* [Busted](http://olivinelabs.com/busted/)\n* [Lust](https://github.com/bjornbytes/lust)\n* [lua-TestMore](https://github.com/fperrad/lua-TestMore)\n* [Luaunit](https://github.com/bluebird75/luaunit)\n\n## Usage\nDefTest is provided as a Defold library project for easy integration in your own project. Add the following line to your project dependencies in game.project:\n\n```lua\nhttps://github.com/britzl/deftest/archive/master.zip\n```\n\nIt is recommended to run your unit tests from its own collection, set as the bootstrap collection in game.project. Add a game object and a script to the collection and use the script to set up your tests. An example:\n\n```lua\nlocal deftest = require \"deftest.deftest\"\nlocal some_tests = require \"test.some_tests\"\nlocal other_tests = require \"test.other_tests\"\n\nfunction init(self)\n    deftest.add(some_tests)\n    deftest.add(other_tests)\n    deftest.run()\nend\n```\n\nAnd a Lua file containing some tests:\n\n```lua\nreturn function()\n    describe(\"Some tests\", function()\n        before(function()\n            -- this function will be run before each test\n        end)\n\n        after(function()\n            -- this function will be run after each test\n        end)\n\n        test(\"Basic arithmetic\", function()\n            assert(1 + 1 == 2)\n        end)\n    end)\nend\n```\n\nMore examples of the Telescope test syntax can be seen in [telescope_syntax.lua](https://github.com/britzl/deftest/blob/master/test/telescope_syntax.lua) and a full example of how to setup and run tests can be seen [in the test folder](https://github.com/britzl/deftest/tree/master/test).\n\n### Custom asserts\nTelescope provides a system for custom asserts with the following asserts available by default:\n\n* assert_blank(a) - true if a is nil, or the empty string\n* assert_empty(a) - true if a is an empty table\n* assert_equal(a, b) - true if a == b\n* assert_error(f) - true if function f produces an error\n* assert_false(a) - true if a is false\n* assert_greater_than(a, b) - true if a \u003e b\n* assert_gte(a, b) - true if a \u003e= b\n* assert_less_than(a, b) - true if a \u003c b\n* assert_lte(a, b) - true if a \u003c= b\n* assert_match(a, b) - true if b is a string that matches pattern a\n* assert_nil(a) - true if a is nil\n* assert_true(a) - true if a is true\n* assert_type(a, b) - true if a is of type b\n* assert_not_blank(a)  - true if a is not nil and a is not the empty string\n* assert_not_empty(a) - true if a is a table, and a is not empty\n* assert_not_equal(a, b) - true if a ~= b\n* assert_not_error(f) - true if function f does not produce an error\n* assert_not_false(a) - true if a is not false\n* assert_not_greater_than(a, b) - true if not (a \u003e b)\n* assert_not_gte(a, b) - true if not (a \u003e= b)\n* assert_not_less_than(a, b) - true if not (a \u003c b)\n* assert_not_lte(a, b) - true if not (a \u003c= b)\n* assert_not_match(a, b) - true if the string b does not match the pattern a\n* assert_not_nil(a) - true if a is not nil\n* assert_not_true(a) - true if a is not true\n* assert_not_type(a, b) - true if a is not of type b\n\nDefTest adds these additional asserts:\n\n* assert_same(...) - true if all values are the same (using deep compare of values)\n* assert_unique(...) - true if all values are unique (using deep compare of values)\n* assert_equal(...) - true if all values are equal (using equality operator, ==)\n\n## Running tests from a CI system\nThe real power of unit tests is as we have learned when the tests can be automated and run for every change made to the code. There are many CI systems available and this project will also show how to integrate with some of the more popular CI systems out there. The main idea is to configure a physical or virtual machine so that tests can be run frequently and with predictable results every time. Once the configuration of the machine is complete a script of some kind executes the tests and depending on the outcome different actions are taken. Failed tests could perhaps trigger e-mail notifications to team members or a dashboard display to light up while successful tests could trigger a build of binaries based on the tested code.\n\nThe tests for this project can either be executed from within Defold or through the [run.sh](https://github.com/britzl/deftest/blob/master/.test/run.sh) script from the command line. The script will download the latest headless version of the Defold engine and the command line build tool (bob.jar), build the project and run the tests.\n\n### Using Travis-CI\nThe tests in this project are run on [Travis-CI](https://travis-ci.org/britzl/deftest). The configuration can be seen in the [.travis.yml](https://github.com/britzl/deftest/blob/master/.travis.yml) file while the bulk of the work is done in the run.sh script.\n\n[![Travis-CI](https://travis-ci.org/britzl/deftest.svg?branch=master)](https://travis-ci.org/britzl/deftest)\n\nFor an up-to-date version of the script and steps needed to run on Travis-CI please refer to the [defold-travis-ci](https://github.com/britzl/defold-travis-ci) project.\n\n### Filtering tests to run\nYou can specify a string pattern (using normal Lua pattern matching) that will be matched against the test names to filter which tests to run:\n\n```Lua\n-- only run tests containing 'foobar'\ndeftest.run({ pattern = \"foobar\" })\n```\n\n### Code coverage\nDefTest can collect code coverage stats to measure how much of your code that is tested. Code coverage data is collected using [LuaCov](https://github.com/keplerproject/luacov), specifically code [from a LuaCov fork](https://github.com/britzl/luacov) where the code has undergone some minor alterations to work well with Defold. Code coverage is not automatically collected. You can enable code coverage collection like this:\n\n```Lua\ndeftest.run({ coverage = { enabled = true } })\n```\n\nWhen the tests have completed a code coverage report will be generated to `luacov.report.out` and raw stats to `luacov.stats.out`. The report can be uploaded directly to a service such as [codecov.io](https://codecov.io) or the stats can be formatted into a report format accepted by other services such as [coveralls.io](http://coveralls.io/).\n\n## Limitations\nUnit testing in Defold works best when testing Lua modules containing pure logic. Testing script and gui_script files is more related to integration tests as it not only involves your code, but also visual components and interaction between the different game objects and the systems provided by the engine. If your scripts contains complex code that you wish to test it is recommended to move the code to a Lua module and test just that module.\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fdeftest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbritzl%2Fdeftest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fdeftest/lists"}