Proverbs

Let not mercy and truth forsake thee: bind them about thy neck; write them upon the table of thine heart.

    Proverbs 3:3

A proverb is basically a simple and concrete saying. The idea is that it expresses a truth based on common sense or experience. Here I'm simply extending that idea to apply to how tools like RSpec use simple, concrete sayings -- in a particular context -- to express a truth. The "truth" in this case is the observable of a test.

Proverbs provides a very thin wrapper around RSpec that provides for more syntax possibilities and thus allows different modes of expression.

More specifically, Proverbs provides an internal DSL, similar to the RSpec Story Runner, which was the predecessor of the Cucumber external DSL provided by Gherkin. A goal of many of these tools is to put an emphasis on communication and they do so by making it somewhat easy to encode that communication as expressions. Tools like Cucumber focus on allowing communication via a description language that is structured by Gherkin keywords.

However, while the ideas behind Gherkin are viable, tools like Cucumber abstract away the nuts and bolts of your tests. Abstraction can be a good thing but Cucumber gives you no choice in the matter. It hides code blocks behind a "call by regular expression" invocation mechanism instead of making those code blocks readily available in the test description.

Proverbs lets you write as much logic beside your specifications as you want by leveraging the RSpec ecosystem with the addition of a Gherkin-like syntax. Beyond that, the syntax is not just limited to Gherkin.

To get the latest stable release, add this line to your application's Gemfile:

gem 'proverbs'

To get the latest code:

gem 'proverbs', git: 'https://github.com/jeffnyman/proverbs'

After doing one of the above, execute the following command:

$ bundle

You can also install Tapestry just as you would any other gem:

$ gem install proverbs

To use Proverbs you simply have to require it within your spec_helper file:

require 'proverbs'

You can then use the DSL that Proverbs provides to structure your tests. Once you've done that, then you simply run your rspec command as normal against your test suite.

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake spec:all to run the tests. The default rake command will run all tests as well as a RuboCop analysis. To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/jeffnyman/proverbs. The testing ecosystem of Ruby is very large and this project is intended to be a welcoming arena for collaboration on yet another test-supporting tool. As such, contributors are very much welcome but are expected to adhere to the Contributor Covenant code of conduct.

The Proverbs gem follows semantic versioning.

To contribute to Proverbs:

1. Fork the project.
2. Create your feature branch. (git checkout -b my-new-feature)
3. Commit your changes. (git commit -am 'new feature')
4. Push the branch. (git push origin my-new-feature)
5. Create a new pull request.

• Jeff Nyman

Proverbs has been inspired by the following projects:

• maniok_bdd
• rspec-gherkin
• rspec example steps
• rspec-steps
• rspec-given
• XSpec

Proverbs is distributed under the MIT license. See the LICENSE file for details.