Document Development Tooling

[plexus]

Dumping this here for future reference, this will need to be expanded with actual explanations of what this all means and probably should become part of DEVELOPMENT.md

• we use Mutant. All new or significantly altered code is expected to be 100% explicitly Mutation covered
• We use Ataru, all code samples in README.md have to actually run. When adding features it's a good idea to add a code sample that both demonstrates and exercises a feature, kind of like a high level test case
• We use bogus instead of rspec-mocks. I switched at one point out of some frustrations with rspec-mocks, and I still haven't fully internalized the Bogus API, so as far as I'm concerned maybe we could switch back at some point, but I don't want both in the same code base. So until further notice if you have to stub/set method expectations, Bogus is the way to go. (@chastell maybe you can tell us why we should stick to Bogus exactly?)
• We use (or soon will be using) Rubocop, so code has to be styled correctly before it goes in. This might be a process, I can imagine disabling some rules at some point
• We aim for compatibility with 1.9.3 and up, as well as JRuby. Rubinius is nice to have but not high priority

[chastell]

RSpec 3 gives you verified doubles, which are the major ‘selling poing’ behind Bogus. RSpec’s verified doubles work a little bit differently, though: they verify the double iff the doubled class is loaded. This has pros and cons: on one hand it lets you do outside-in implementation without having empty method calls on the lower layers, on the other it does not verify the double if for some reason you forgot to load the doubled class.

That said, there are two Bogus features that RSpec does not have (yet?):

• faking roles lets you say things like ‘this fake represents any logger in the system’ and won't let you stub/mock method calls that are not supported by all loggers;
• contract tests let you check ‘now that I have stubbed/mocked these method calls (with these arguments and these return values) all over my tests, would the real calls with these arguments result in these return values?’ – they basically force you to write specs for the doubles that you use so that not only the method names and arity are checked, but actually their return values (given particular arguments).