-specit assists in creating and running executable specifications.
-The commandline runner uses nose to discover and execute
-specifications using flexible matching rules so that you do
-not need to use distracting unittest constructs like "def test..."
-It also provides an "expect" construct with extensible matchers
-that enable you to describe the behaviour of your software using simple,
-pythonic BDD style grammar. Here is a simple example to illustrate
-how you may create specs using expect::
+Specit is no longer actively developed. It has been replaced by:
+- compare: for the pluggable `expect` syntax
+-- package: http://pypi.python.org/pypi/compare/
+-- source: https://github.com/rudylattae/compare/
+-- docs: http://packages.python.org/compare/
+- checkit: enables `nose` to detect and run test cases defined using BDD style "describe" and "it"
+-- package: http://pypi.python.org/pypi/checkit/
+-- source: https://bitbucket.org/rudylattae/checkit/
- >>> from specit import expect
- >>> expect(greet).to_return('Hello you')
+Specit is a minimalistic tool to assist developers in creating
+and validating executable specifications for python software. It
-1. Provide a readable, pythonic syntax for defining expectations
-in executable specifications.
+1. Provide a readable, pythonic syntax for defining expectations in your example specifications.
+2. Provide a simple tool for validating your specifications.
-2. Provide a simple tool for discovering and running executable
-specifications in Python.
-In Python land, the defacto unit testing product is the builtin unittest
-module. I always have difficulty creating "unit specs" using unittest
-because the grammar and style it promotes are in my opinion, counter-intuitive
-and not pythonic. I needed an alternative component-level specification
-tool that would allow me to create and run specs in a manner that encourages
-me to focus on designing or discovering the behaviour of my software NOT on
-So I `google'd <http://www.google.com/search?q=python+bdd+tools>`_ and
-I found a few intriguing options which I decided against because of the
-* `SpecLoud <https://github.com/hugobr/specloud>`_: it looks good but it only provides a runner and the installation is not as simple as I would like.
-* `Should-DSL <http://www.should-dsl.info>`_: even though I was draw to Should-DSL earlier on, I just could not get over the fact that I need to wrap the "should"/"should_not" constructs with pipes "||". It seems un-pythonic.
-* `Describe <https://github.com/jeffh/describe>`_: I like the ".should" matcher syntax. However, it seems there is a lot going on under the hood -- I need something brain-dead simple.
-I strongly urge you to take a look at the above projects. They are all good
-projects in many way and one of them could be exactly what you are looking for.
-As with anything in life, YMMV.
-After eliminating the potentials above, I decided to create specit because
-I wanted a compact "batteries included" tool which would help me create and
-run pythonic specifications.
-Since `nose <http://somethingaboutorange.com/mrl/projects/nose>`_
-is already a great test discoverer/runner with a healty eco-system of plugins,
-I figured it would be best for specit to leverge it's abilities. i.e. Life's
-short, so don't re-invent the wheel unless you absolutely must.
+To this end, specit provides two components to simplify your
+work with specs. The **expect** construct allows you to indicate
+verifyable expectations of your software. It is a replacement for
+the "self.assert..." syntax. The **specit** command uses
+`Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ to
+validate your specifications.
- uses nose for discovering and running specs
- provides a base set of matchers for defining expectations
- easy to extend with custom matchers
+All the requirements for using specit are auto-installed if you
+use pip or easy_install. Here they are:
+- `Nose <http://somethingaboutorange.com/mrl/projects/nose>`_
+The easiest way to install specit is with ``pip install spectit``
+or with ``easy_install specit``. Alternatively, you may
+`download <http://pypi.python.org/pypi/specit>`_ the
+source package from PyPI, extract it and install it using
+``python setup.py install``.
+When you install the package, you get two shiny components that
+may help you achieve the goals above.
+**"expect"**, is the grammar component. It provides a construct with
+extensible matchers that enables you to describe the expected
+behaviour of your software using a pythonic BDD manner. Again, this
+helps you maintain your flow of thought without succumbing to
+test-focused non-pythonic distrations like "self.assertEqual(s)...",
+**"specit"**, is the commandline component. It uses nose to discover
+and execute specifications using flexible matching rules so that you
+are not limited to using distracting unittest (test focused) constructs
+like "def test..." or name your files "test...py".
+Here is a trivial example of the clarity you gain when you
+employ the "expect" construct in your specs::
+ > cat greeting_specs.py
+ from specit import expect
+ from greeting import greet
+ expect(greet).to_return('Hello you')
+Even more iteresting is the fact that you no longer have to
+subject yourself to the unnecessary cruft needed for unittest
+test cases. You can now create a spec like this::
+ class DescribeCool(object):
+ class MyAwesomeSpecs():
+ def should_always_smile(self):
+Finally, when you want to validate your software against the sepcs,
+simply run the commandline tool "specit" in your project
-If you have pip installed, you may install upgrade or uninstall
-specit with these commands::
- > pip install -U specit
-If you do not have pip you may use easy install::
-If you do not have pip or easy_install, you may
-the source distribution archive. Extract its contents,
-go into the resulting "specit" directory and run::
- > python setup.py install
-Verifying expectations with the basic matchers
-Below is a simple example showing how you use the builtin matchers
-to craft readable specifications for your code::
- >>> from specit import expect
- >>> expect(fruit).to_equal('Orange')
- >>> expect(fruit).to_equal('Apple')
- Traceback (most recent call last):
- AssertionError: Expected 'Orange' to equal 'Apple'
-Creating and using custom matchers
-A specit matcher is a regular python function that can be
-wired into the Expect class. You may extend specit with
-custom matchers that make make your examples succinct and
- >>> from specit import expect, matcher, ensure
- ... def to_be_citrus(self):
- ... ensure(self.actual in ['Orange'], True, "Expected %s to be a citrus fruit" % self.actual)
- >>> expect(fruit).to_be_citrus()
-Running your specs from the command line
-When you install specit, you get a command line tool "specit"
-installed into your Python scripts directory. Assuming the your
-scripts dir is on yout PATH, you will be able to execute your
-specifications simply by calling specit inside your project.
-Below is a trivial example project layout for a simple module::
-From the root directory of your project, you may run the
-specifications in specs.py like so::
-If you wish to see a detailed output, just run specit with the '-v'
-There are many more options you may pass to the "specit" command.
-Please see the "How it works" section for more information.
-The specit commandline tool "specit" is simply a wrapper for nose,
-specifically, the "nosetests" command that is installed with nose.
-The specit command basically calls the nosetests command with some arguments
-that tell it to look for tests in files with names like "spec(s)", "example(s)",
-etc. It also tells nosetests to treat methods or classes with names like
-"Describe...", "...Specs", "it...", etc. as test cases, or in BDD terms
-Nose itself provides a lot of useful features out of the box. Please
-refer to the `Nose site <http://somethingaboutorange.com/mrl/projects/nose>`_
-for further information.
-If you are interested in knowing more about the options you can pass to
-the specit (nosetests wrapper) command, you should look at the
-`nose usage documentation <http://somethingaboutorange.com/mrl/projects/nose/1.0.0/usage.html#options>`_.
I welcome any questions or feedback about bugs and suggestions on how to
-Let me know what you think about specit. I am on twitter
+improve specit. Let me know what you think about specit. I am on twitter
`@RudyLattae <http://twitter.com/RudyLattae>`_ . I appreciate constructive
criticsms or high fives :)
`issue <https://bitbucket.org/rudylattae/specit/issues>`_ with details
of what you would like to see. I'll take a look at it and work with you to either kill
the idea or implement it.
-To contribute to specit, fork it, make your modifications and
-create a pull request. I'll be more than happy to merge in your work.
-I'll be more than happy to merge in your work.
-Please ensure that you provide supporting specs for your contribution. Also if you are
-creating a new feature or fixing a bug, I encourage you to create an issue for it
-in order to minimize duplication of effort.
-specit was inspired by and/or leverages concepts from:
-- `Jasmine BDD <http://pivotal.github.com/jasmine>`_
-- `SpecLoud <https://github.com/hugobr/specloud>`_
-Copyright (c) 2010-2011 - Rudy Lattae. Released under the New BSD License.