• Stars
    star
    160
  • Rank 229,662 (Top 5 %)
  • Language
    Lua
  • Created almost 15 years ago
  • Updated almost 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A highly customizable test library for Lua that allows declarative tests with nested contexts.

Telescope

Telescope is a highly customizable test library for Lua that allows for declarative tests with nested contexts.

Features

  • Compatible with Lua 5.1 and 5.2.
  • Nestable test contexts/descriptions.
  • BDD-style spec names.
  • Before/after functions per context.
  • Integrated code coverage reports using Luacov.
  • You can easily add your own assertions.
  • Many different formatting options for tests and reports.
  • Simple, well documented API makes it easy to extend/hack.
  • Command line runner allows you to input Lua snippet callbacks, so you can, for example, drop to a debugger on failed tests, or wrap test calls around a profiler, etc.

An Example

context("A context", function()
  before(function() end)
  after(function() end)
  context("A nested context", function()
    test("A test", function()
      assert_not_equal("ham", "cheese")
    end)
    context("Another nested context", function()
      test("Another test", function()
        assert_greater_than(2, 1)
      end)
    end)
  end)
  test("A test in the top-level context", function()
    assert_equal(3, 1)
  end)
end)

Getting it

You can install Telescope using Luarocks:

sudo luarocks install telescope

You can also check out the source code from Git, and install via "make" if you prefer:

git clone git://github.com/norman/telescope.git
cd telescope
make install

Running your tests

Telescope comes with a command-line test runner named tsc. Simply run:

tsc my_test_file.lua

Or perhaps

tsc -f test/*.lua

The full test output (what you get using "-f") from the examples given would be:

------------------------------------------------------------------------
A context:
A nested context:
  A test                                                             [P]
  Another nested context:
    Another test                                                     [P]
A test in the top-level context                                      [F]
------------------------------------------------------------------------
A test with no context                                               [U]
Another test with no context                                         [U]
------------------------------------------------------------------------
This is a context:
This is another context:
  this is a test                                                     [U]
  this is another test                                               [U]
  this is another test                                               [U]
------------------------------------------------------------------------
8 tests 2 passed 3 assertions 1 failed 0 errors 5 unassertive 0 pending

A test in the top-level context:
Assert failed: expected '3' to be equal to '1'
stack traceback:
  ...ib/luarocks/rocks//telescope/scm-1/lua/telescope.lua:139: in function 'assert_equal'
  example.lua:18: in function <example.lua:17>
  [C]: in function 'pcall'
  ...ib/luarocks/rocks//telescope/scm-1/lua/telescope.lua:330: in function 'invoke_test'
  ...ib/luarocks/rocks//telescope/scm-1/lua/telescope.lua:362: in function 'run'
  ...usr/local/lib/luarocks/rocks//telescope/scm-1/bin/ts:147: in main chunk
  [C]: ?

Telescope tells you which tests were run, how many assertions they called, how many passed, how many failed, how many produced errors, how many provided a name but no implementation, and how many didn't assert anything. In the event of any failures or errors, it shows you stack traces.

You can customize the test output to be as verbose or silent as you want, and easily write your own test reporters - the source is well documented.

You can pass in snippets of Lua code on the command line to run as callbacks for various test success/failure scenarios, and easily customize the output or use Telescope with other applications.

You can see all the available command-line options, and some examples by running:

tsc -h

More Examples

-- Tests can be outside of contexts, if you want
test("A test with no context", function()
end)

test("Another test with no context", function()
end)

-- Contexts and tests with various aliases
spec("This is a context", function()
  describe("This is another context", function()
    it("this is a test", function()
    end)
    expect("this is another test", function()
    end)
    should("this is another test", function()
    end)
  end)
end)

Even More Examples

-- change the name of your test or context blocks if you want something
-- different
telescope.context_aliases = {"specify"}
telescope.test_aliases = {"verify"}

-- create your own assertions
telescope.make_assertion("longer_than", "%s to be longer than %s chars",
  function(a, b) return string.len(a) > b end)
-- creates two assertions: assert_longer_than and assert_not_longer_than,
-- which give error messages such as:
-- Assertion error: expected "hello world" to be longer than 25 chars
-- Assertion error: expected "hello world" not to be longer than 2 chars

-- create a test runner with callbacks to show progress and
-- drop to a debugger on errors
local contexts = telescope.load_contexts(file)
local results = telescope.run(contexts, {
 after = function(t) io.stdout:write(t.status_label) end,
 error = function(t) debug.debug() end
})

-- call "tsc" on the command line with a callback to generate a custom report
tsc --after="function(t) print(t.status_label, t.name, t.context) end" example.lua

Author

Norman Clarke

Please feel free to email me bug reports or feature requests.

Acknowledgements

Telescope's initial beta release was made on Aug 25, 2009 - the 400th anniversary of the invention of the telescope.

Thanks to ScrewUnit, Contest and Luaspec for inspiration.

Thanks to Eric Knudtson for helping me come up with the name "Telescope."

License

The MIT License

Copyright (c) 2009-2012 Norman Clarke

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

More Repositories

1

friendly_id

FriendlyId is the “Swiss Army bulldozer” of slugging and permalink plugins for ActiveRecord. It allows you to create pretty URL’s and work with human-friendly strings as if they were numeric ids for ActiveRecord models.
Ruby
6,109
star
2

babosa

A library for creating slugs. Babosa is an extraction and improvement of the string code from FriendlyId, intended to help developers create similar libraries or plugins.
Ruby
528
star
3

disqus

A Ruby library for the Disqus commenting API and Javascript widgets.
Ruby
250
star
4

haml-scaffold

Rails scaffold generator that outputs Haml and better functional tests.
Ruby
114
star
5

squirm_rails

Easily use and manage Postgres stored procedures with Active Record.
Ruby
73
star
6

friendly_id-globalize

Globalize support for FriendlyId
Ruby
65
star
7

ambry

Ambry is a database and ORM replacement for (mostly) static models and small datasets. It provides ActiveModel compatibility, and flexible searching and storage.
Ruby
56
star
8

lua-haml

Haml for Lua
Lua
53
star
9

hello-lua

A demo of how to make simple C modules for Lua
C
34
star
10

squirm

A library that simplifies working with Postgres stored procedures.
Ruby
18
star
11

grackle

A static blog generator written in Lua
Lua
18
star
12

luacov

LuaCov is a simple coverage analyzer for Lua code. (fork of official CVS repo)
16
star
13

lua-postgres

A basic Postgres driver for Lua
C
16
star
14

has_image

A lightweight and hackable library for attaching images to ActiveRecord models.
Ruby
16
star
15

phonenumber

Allows parsing and formatting of phone numbers
Ruby
16
star
16

hops

A lightweight, pluggable web framework for Lua
Lua
15
star
17

lua-devtools

An irb-workalike for Lua, and a command-line debugger with readline support.
Lua
15
star
18

tlua

A simple task runner for Lua - now abandoned because I think it's just easier to use plain old Makefiles.
Lua
14
star
19

spanish

Linguistic utilities for working with Spanish words.
Ruby
12
star
20

enc

Notes and slides from my Encodings talk at RubyConf Brasil 2010
Ruby
12
star
21

nearby

Quick and easy geocoding using Geonames.org data and TokyoCabinet.
Ruby
10
star
22

nt54

Argentine phone number parsing, validating, formatting and meta-info
Ruby
10
star
23

active_record_random

Monkey patch to ActiveRecord to allow :order => :random that works the same for MySQL, SQLite and Postgres.
9
star
24

fatalistic

Table locking for Active Record
Ruby
9
star
25

yourbugreportneedsmore.info

The yourbugreportneedsmore.info website
HTML
8
star
26

friendly_id_manual_slug_demo

A Rails 3 app showing how to manually control FriendlyId slugs
Ruby
7
star
27

mongrel2_wsapi

In-progress Lua WSAPI adapter for Mongrel2
Lua
6
star
28

base-site-generator

The current base layout and helpers I'm using to scaffold quick projects. Feel free to use if and as you wish.
Ruby
6
star
29

squirm_model

Model API for Squirm
Ruby
5
star
30

micro_factory

Minimal factories for Active Record.
Ruby
4
star
31

utf8_utils

Utilities for cleaning up UTF8 strings.
Ruby
4
star
32

phonology

Phonology utilities for Ruby
Ruby
3
star
33

dotfiles

My dotfiles
Vim Script
2
star
34

wsapi_test

Mock connector for unit testing WSAPI apps. TEMP. Go here instead: http://github.com/norman/wsapi
Lua
2
star
35

hash_formatter

Hash Formatter is a library that formats Ruby hashes for code editors.
Ruby
2
star
36

gem_init

My Ruby Gem initialization biolerplate
Ruby
2
star
37

luaargentina

luaargentina.org website
2
star
38

luadns-zones

My DNS zones hosted on LuaDNS.
Lua
1
star
39

friendly_id_join_test

Temporary debugging repo, don't follow
Ruby
1
star
40

haml_textarea_bug

Demonstrates a bug in Haml
Ruby
1
star
41

vim-files

My vim files
Vim Script
1
star
42

friendly_id_sequel

An adapter which allows you to use FriendlyId with Sequel::Model
Ruby
1
star