Behaviour Driven Development for Tcl

TclSpec is a Behaviour Driven Development (BDD) Framework for the Tcl language.

It is based on RSpec, a BDD Framework for Ruby.

• Tcl 8.5 or higher
• Next Scripting Framework 2.0b3 or higher

Put the tclspec folder into one of the folders denoted in your Tcl's $auto_path.

TclSpec allows you to describe the behaviour of your code using a structure of describe and it blocks.

describe Order {
    it "sums the prices of its line items" {
        set order [Order new]
        $order add_entry [LineItem new -item [Item new -price "1.11"]]
        $order add_entry [LineItem new -item [Item new -price "2.22" -quantity 2]]

        expect [$order total] to equal 5.55
    }
}

Groups can be nested using example or context keywords:

describe Order {
    context "with no items" {
        it "behaves one way" {
            # ...
        }
    }

    context "with one item" {
        it "behaves another way" {
            # ...
        }
    }
}

TclSpec comes with a list of built in matchers that you can use to express expected outcomes inside your specifications.

expect $actual to equal $expected

expect $actual to be >  $expected
expect $actual to be >= $expected
expect $actual to be <= $expected
expect $actual to be <  $expected
expect $actual to be_within $delta of $expected

expect $actual to be true
expect $actual to be false

expect { ... } to raise_error
expect { ... } to raise_error -code SomeErrorCode
expect { ... } to raise_error -message "Some error message"
expect { ... } to raise_error -code SomeErrorCode -message "Some error message

Tclspec includes stubbing and mocking functionality for plain Tcl procs and nx objects.

Test stubs allow you to switch out the implementation of a proc during the runtime of an example. After the example has been executed, the test stub will be cleaned up and removed.

Stubs should be used if you want to force specific code behaviour in your examples or if you want to prevent the call to the original implementation of a procedure in your test case.

stub_call "::roll_die" -and_return 3

$die stub "roll" -and_return 3

In the bin folder, you can find the tclspec executable, which is used to run tclspec. Calling tclspec without any arguments will execute all spec files located in the spec folder in the current working directory. Additionally, you can either pass individual files or folders to run.

If you want to contribute to TclSpec, please open a ticket in the Github Issue Tracker and let me know what you want to work on, so I can provide you with feedback upfront.

If you have changes/patches, please open a Github Pull Request so that I can review your changes. I'll try to get back to you as soon as passible with my comments.