diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2e4daca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# TestEZ Changelog + +## Current master +* No changes + +## 1.0.0 (TODO: Date) +* Initial release \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ccbcb22..55108f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,2 +1,72 @@ # Contributing to TestEZ -TODO \ No newline at end of file +Thanks for considering contributing to TestEZ! This guide has a few tips and guidelines to make contributing to the project as easy as possible. + +## Bug Reports +Any bugs (or things that look like bugs) can be reported on the [GitHub issue tracker](https://github.com/Roblox/TestEZ/issues). + +Make sure you check to see if someone has already reported your bug first! Don't fret about it; if we notice a duplicate we'll send you a link to the right issue! + +## Feature Requests +If there are any features you think are missing from TestEZ, you can post a request in the [GitHub issue tracker](https://github.com/Roblox/TestEZ/issues). + +Just like bug reports, take a peak at the issue tracker for duplicates before opening a new feature request. + +## Working on TestEZ +To get started working on TestEZ, you'll need: +* Git +* Lua 5.1 +* [LuaFileSystem](https://keplerproject.github.io/luafilesystem/) (`luarocks install luafilesystem`) +* [Luacheck](https://github.com/mpeterv/luacheck) (`luarocks install luacheck`) +* [LuaCov](https://keplerproject.github.io/luacov) (`luarocks install luacov`) + +Once you have all of these installed, you can run the `install-dependencies` script to grab a couple additional local dependencies automatically. + +Finally, you can run all of TestEZ's tests with: + +```sh +lua spec.lua +``` + +Or, to generate a LuaCov coverage report: + +```sh +lua -lluacov spec.lua +luacov +``` + +## Pull Requests +Before starting a pull request, open an issue about the feature or bug. This helps us prevent duplicated and wasted effort. These issues are a great place to ask for help if you run into problems! + +Before you submit a new pull request, check: +* Code Style: Match the existing code! +* Changelog: Add an entry to [CHANGELOG.md](CHANGELOG.md) +* Luacheck: Run [Luacheck](https://github.com/mpeterv/luacheck) on your code, no warnings allowed! +* Tests: They all need to pass! + +### Code Style +Try to match the existing code style! In short: + +* Tabs for indentation +* Double quotes +* One statement per line + +Eventually we'll have a tool to check these things automatically. + +### Changelog +Adding an entry to [CHANGELOG.md](CHANGELOG.md) alongside your commit makes it easier for everyone to keep track of what's been changed. + +Add a line under the "Current master" heading. When we make a new release, all of those bullet points will be attached to a new version and the "Current master" section will become empty again. + +### Luacheck +We use [Luacheck](https://github.com/mpeterv/luacheck) for static analysis of Lua on all of our projects. + +From the command line, just run `luacheck lib` to check the TestEZ source. + +You should get it working on your system, and then get a plugin for the editor you use. There are plugins available for most popular editors! + +### Tests +When submitting a bug fix, create a test that verifies the broken behavior and that the bug fix works. This helps us avoid regressions! + +When submitting a new feature, add tests for all functionality. + +We use [LuaCov](https://keplerproject.github.io/luacov) for keeping track of code coverage. We'd like it to be as close to 100% as possible, but it's not always easy. \ No newline at end of file diff --git a/README.md b/README.md index 833ee2f..d6a998e 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@
 
-TestEZ can run within Roblox itself, as well as inside [Lemur](https://github.com/LPGhatguy/Lemur) for testing on CI systems. +TestEZ can run within Roblox itself, as well as inside [Lemur](https://github.com/LPGhatguy/Lemur) for testing on CI systems. We use it at Roblox for testing lots of Lua code, as well as libraries like [Rodux](https://github.com/Roblox/Rodux). It provides an API that can run all of your tests with a single method call as well as a more granular API that exposes each step of the pipeline. @@ -100,7 +100,7 @@ Often during development, you'll want to only run the test that's concerned with TestEZ provides the `SKIP()` and `FOCUS()` functions to either skip or focus the block that the call is contained in. -This mechanism does not work for `it` blocks, where you can instead is `itSKIP` and `itFOCUS`. This is because the code inside `it` blocks is not run until the test is executed. +This mechanism does not work for `it` blocks, where you can instead use `itSKIP` and `itFOCUS`. This is because the code inside `it` blocks is not run until the test is executed. For example, I might want to run the tests targeting a specific method for my `DateTime` module: @@ -125,10 +125,10 @@ end ***`FOCUS` and `SKIP` are intended exclusively for development; future versions of TeztEZ will be able to detect this when running in a CI system and fail tests!*** -## TestEZ API +## TestEZ Test API ### `describe(phrase, callback)` -This function creates a new `describe` block. These blocks correspond to the things that are being tested. +This function creates a new `describe` block. These blocks correspond to the **things** that are being tested. Put `it` blocks inside of `describe` blocks to describe what behavior should be correct. @@ -143,7 +143,7 @@ end) ``` ### `it(phrase, callback)` -This function creates a new 'it' block. These blocks correspond to the behaviors that should be expected of the thing you're testing. +This function creates a new 'it' block. These blocks correspond to the **behaviors** that should be expected of the thing you're testing. For example: @@ -216,6 +216,9 @@ The `describe` and `it` syntax in TestEZ is based on the [Behavior-Driven Develo The `expect` syntax is based on Chai, a JavaScript assertion library commonly used with Mocha. Similar expectation systems are also used in RSpec and Ginkgo, with slightly different syntax. +## Contributing +Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for information. + ## License TestEZ is available under the Apache 2.0 license. See [LICENSE](LICENSE) for details.