Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    ciaopublic

    Ciao

    Ciao is a simple command line utility for testing http(s) requests and generating API documentation.

    Scripts are written in coffee-script, however it's important to note that they are interpreted, not executed.

    Basic uptime script:

    #> Check Google is still running
    host: 'www.google.co.uk'
     
    #? Should have company name
    response.body.should.containEql 'Google'

    HTML test script:

    #> Twitter home page
    port: 443
    protocol: 'https:'
    host: 'twitter.com'
     
    #? Login form
    $('div.front-signin input#signin-email').length.should.eql 1
    $('div.front-signin input#signin-password').length.should.eql 1
    $('div.front-signin button[type="submit"]').length.should.eql 1

    JSON webservice script:

    #! Requried Headers
    headers: 'User-Agent': 'Ciao/Client 1.0'
     
    #> Github API call for node.js README
    port: 443
    protocol: 'https:'
    host: 'api.github.com'
    path: '/repos/joyent/node/readme'
    headers: 'Accept': 'application/json'
     
    #? Readme is available on Github
    response.statusCode.should.equal 200
    response.should.have.header 'server', 'GitHub.com'
     
    #? Should be what we are looking for...
    json.sha.should.match /^[a-z0-9]{40}/
    json.should.containEql
      type: 'file'
      path: 'README.md'
      url: 'https://api.github.com/repos/joyent/node/contents/README.md'
      html_url: 'https://github.com/joyent/node/blob/master/README.md'
      git_url: 'https://api.github.com/repos/joyent/node/git/blobs/' + json.sha

    When you run a script, documentation is produced. eg: Github API Example - Documentation


    Writing Scripts

    Ciao uses a special syntax to declare the start and end of code blocks.

    Currently 4 interpreter directives are supported:

    • #! before block, this is merged in to every request block.
    • #> request block, this is the main http(s) query definition block.
    • #? assertion block, this defines a test case which the result should conform to.
    • ## junk block, all code in this block will be ignored by the parser.

    Each directive is followed by a single space and a directive title

    eg. #> Contact page is available defines a #> request block with the title Contact page is available.

    The title is used for reporting & documentation, so the better your titles, the easier life will be for you.


    Installing Ciao

    To install the most stable ciao binary globally on your system via npm you can simply:

    $ [sudo] npm install -g ciao
    $ ciao --help

    NPM

    Note: you will need node and npm installed first.

    The easiest way to install node.js is with nave.sh by executing [sudo] ./nave.sh usemain 0.10


    Running Scripts

    peter@edgy:/var/www/ciao$ ciao --help
     
      Usage: ciao [options] <file ...>
     
      Options:
        -h, --help                 output usage information
        -V, --version              output the version number
        -g, --gist [url]           load script from github gist
        -c, --conf [dir]           an additional config file to load after ciao.json
        -s, --silent               disable reporters
        -v, --verbose              report full requests and responses on error
        -d, --documentation [dir]  generate documentation in output dir

    Running a single script

    $ ciao scripts/examples/basic.coffee 
     
     GET http://www.google.co.uk/ scripts/examples/basic.coffee 
     ✓ Status: 200 OK
     
     GET http://www.google.co.uk/ scripts/examples/basic.coffee 
     ✓ Response.body should contain company name

    Running all scripts in a directory

    You can also use ciao on directories to recursively run all scripts.

    $ ciao scripts/

    Running a gist as a script

    You can run remote scripts from github by providing the gist suffix or url.

    $ ciao --gist missinglink/4678610
    $ ciao --gist https://gist.github.com/missinglink/4678610

    Note: The way the gist flag behaves has changed since 0.1.8, please upgrade if you have issues.


    Requests

    The ciao request format is the same as that of the node.js native http client http.request.

    All #> request blocks have access to an object named config which contains all the static configuration properties defined in the ciao config. (as discussed below)

    Request properties

    • host A domain name or IP address of the server to issue the request to. Defaults to 'www.example.com'.
    • hostname To support url.parse() hostname is preferred over host
    • port Port of remote server. Defaults to 80.
    • method A string specifying the HTTP request method. Defaults to 'GET'.
    • path Request path. Defaults to '/'. Should include query string if any. E.G. '/index.html?page=12'
    • headers An object containing request headers.
    • auth Basic authentication i.e. 'user:password' to compute an Authorization header.
    • body If body is an object then JSON.stringify will be run on it before sending.

    Full http.request reference: http://nodejs.org/api/http.html#http_http_request_options_callback

    Examples

    #> Post data to a JSON web service
    path: '/blog/article'
    method: 'POST'
    headers:
      'Accept': 'application/json'
      'Content-Type': 'application/json'
    body: 
      title: 'My amazing blog post'
      body: '@todo'
    #> Get package details from the npm registry
    host: 'registry.npmjs.org'
    path: '/ciao/latest'
    headers: 'Accept': 'application/json'
     
    #? Should have preferGlobal set to true
    json.preferGlobal.should.be.true

    Assertions

    You can add assertions to your scripts by including #? assertion blocks.

    Currently #? assertion blocks only provide the functionality of the should js framework, but I am looking at adding more assertion libraries in the future.

    Each test case has access to four objects named title, response, json & $.

    • title is simply the title specified in the interpreter directive (as discussed above)
    • response contains 3 properties returned by http.request
      • body contains the body of the http(s) response.
      • statusCode contains the status code of the http(s) response.
      • headers contains an array of headers that were returned.
    • json the result of parsing the response.body with JSON.parse (empty for invalid json).
    • $ the result of parsing the response.body with cheerio (a familiar jQuery-like API).

    Examples

    #? Test the response code
    response.statusCode.should.equal 200
     
    #? Test a header is set
    response.should.have.header 'server'
     
    #? Test a header value
    response.should.have.header 'server', 'apache'
     
    #? Test body contains string
    response.body.should.containEql 'Bingo Bango Bongo!'
     
    #? Test body contains regex
    response.body.should.match /^[a-z0-9]{40}/
     
    #? Test json object contains properties
    json.should.containEql {
      id: "10000000000000000000",
      name: "Bingo Bango Bongo!"
    }
     
    #? Check for a redirect
    response.should.have.header 'location', 'http://www.example.com/'

    should.js reference: https://github.com/visionmedia/should.js/

    Testing the DOM

    Since version 0.1.8 you can test DOM elements in your source using a jQuery-like syntax.

    #> Wikipedia home page
    host: 'en.wikipedia.org'
    path: '/wiki/Main_Page'
     
    #? Count stylesheets
    $('link[rel="stylesheet"]').length.should.eql 2
     
    #? Page structure
    $('body.mediawiki > div#mw-page-base').length.should.eql 1
     
    #? Check headers are correctly rendered
    $('span.mw-headline').first().text().should.eql "From today's featured article"
    $('span.mw-headline').eq(1).text().should.eql "Did you know..."
    $('span.mw-headline').eq(2).text().should.eql "Today's articles for improvement"
    $('span.mw-headline').eq(3).text().should.eql "In the news"
    $('span.mw-headline').eq(4).text().should.eql "On this day..."
    $('span.mw-headline').last().text().should.eql "Wikipedia languages"

    cheerio reference: https://github.com/MatthewMueller/cheerio


    Project Settings

    Ciao looks for a project-wide configuration file called ciao.json in your current working directory.

    The defaults section is merged in to every request that is made, it's useful for specifying global request properties such as host and port.

    The config section is useful for storing session tokens or any sort of data you would like available to #! before or #> request blocks.

    Example ciao.json

    {
      "defaults": {
        "host": "www.google.co.uk",
        "port": 80,
        "headers": {
          "User-Agent": "Ciao/Client 1.0"
        }
      },
      "config": {
        "bingo": "bango"
      }
    }

    Dynamic Project Settings

    If you require your settings to be generated before the test suite runs then you may use a file called ciao.js or ciao.coffee instead of ciao.json.

    This is particularly useful for running fixtures or any other local or remote code before your tests start.

    Dynamic configurations must export their settings with module.exports or an error will be thrown.

    Note: This feature was introduced in 0.3.1, please upgrade if you have issues.


    Generate Documentation

    Ciao can generate documentation for each #> request, the resulting response and all #? assertion blocks.

    The documentation is in markdown format and is available in the directory specified using the -d flag.

    eg. To generate documentation in ./doc for all scripts in ./scripts:

    $ ciao -d doc scripts

    An example generated documentation file can be found here: Github API Example - Documentation


    How it works

    When parsing script & config files ciao launches child processes to excute the coffee-script source. This isolates the main thread from malicious code and ensures the fastest execution of tests.

    All the requests are launched asyncronously using http.request.

    After a response comes back from the target server; all #? assertion blocks are fired asyncronously in a seperate child process.

    NPM Module

    The ciao npm module can be found here: https://npmjs.org/package/ciao

    Github Pages

    A prettier version of this readme is available here: http://missinglink.github.com/ciao/

    Contributing

    Please fork and pull request against upstream master on a feature branch.

    Pretty please; provide unit tests and script fixtures in the test and fixtures directories.

    Getting Set Up

    $ git clone git@github.com:missinglink/ciao.git ciao
    $ cd ciao
    $ npm install
    $ npm test
    $ ./bin/ciao scripts/examples

    Running Unit Tests

    The unit test suite is run using mocha

    $ npm test

    Continuous Integration

    Travis tests every release against node versions 0.6 0.8 & 0.10

    Build Status

    Running Ciao test scripts

    This will execute all tests in the ./scripts directory and write documentation in the ./doc directory.

    $ npm run ciao

    Known bugs

    It's early stages yet; there are a bunch of issues reported here: https://github.com/missinglink/ciao/issues

    Please report everything as it comes up, no matter how small.

    Code review

    If you would like a code review or to open a feature discussion, please fork and pull request against upstream master.

    Project goals

    Short term

    • Stability
    • Cool Functionality
    • Ease of use

    Mid term

    • Improved reporters
    • Improved documentors
    • Web interface

    Long term

    • Scheduled builds
    • Hosted CI solution

    Bitdeli Badge

    Keywords

    none

    install

    npm i ciao

    Downloadslast 7 days

    83

    version

    1.0.0

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar
    • avatar