Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some notes on conventions in test writing #734

Merged
merged 1 commit into from
Dec 10, 2015
Merged

Add some notes on conventions in test writing #734

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,10 +114,27 @@ Write about https://github.com/non/cats/pull/36#issuecomment-72892359

### Write tests

Tests go into the tests module, under the `cats.tests` package. Cats tests
should extend `CatsSuite`. `CatsSuite` integrates ScalaTest with Discipline
for law checking, and imports all syntax and standard instances for
convenience.
- Tests for cats-core go into the tests module, under the `cats.tests` package.
- Tests for additional modules, such as `free`, go into the tests directory within that module.
- Cats tests should extend `CatsSuite`. `CatsSuite` integrates [ScalaTest](http://www.scalatest.org/)
with [Discipline](https://github.com/typelevel/discipline) for law checking, and imports all syntax and standard instances for convenience.
- The first parameter to the `checkAll` method provided by
[Discipline](https://github.com/typelevel/discipline), is the name of the test and will be output to the
console as part of the test execution. By convention:
- When checking laws, this parameter generally takes a form that describes the data type being tested.
For example the name *"Validated[String, Int]"* might be used when testing a type class instance
that the `Validated` data type supports.
- An exception to this is serializability tests, where the type class name is also included in the name.
For example, in the case of `Validated`, the serializability test would take the form,
*"Applicative[Validated[String, Int]"*, to indicate that this test is verifying that the `Applicative`
type class instance for the `Validated` data type is serializable.
- This convention helps to ensure clear and easy to understand output, with minimal duplication in the output.
- It is also a goal that, for every combination of data type and supported type class instance:
- Appropriate law checks for that combination are included to ensure that the instance meets the laws for that type class.
- A serializability test for that combination is also included, such that we know that frameworks which
rely heavily on serialization, such as `Spark`, will have strong compatibility with `cats`.
- Note that custom serialization tests are not required for instances of type classes which come from
`algebra`, such as `Monoid`, because the `algebra` laws include a test for serialization.

TODO

Expand Down