first commit

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+coverage
+reports

LICENSE.md

@@ -0,0 +1,23 @@
+```
+The MIT License (MIT)
+
+Copyright (c) 2016 mobilcom-debitel GmbH
+
+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.
+```

README.md

@@ -0,0 +1,148 @@
+# Got Swag?
+
+A tool to test Swagger-powered APIs automatically through monkey testing.
+Also allows for custom tests written directly in Swagger files
+or in separate test suites.
+Includes command-line and programmatic interfaces.
+Install via `npm install got-swag -g`.
+
+<img src="img/swagmonkey.jpg" width="400">
+
+## Usage
+
+```
+got-swag <url> ... [-m] [-t <ms>] [-T] [-v] [-w]
+  Test a Swagger URL or file (YAML). Additional files are merged.
+
+Options:
+  -m, --monkey        Run monkey tests on GET endpoints
+  -t, --timeout <ms>  Set a timeout (in milliseconds) for test step execution,
+                      default is 2000 ms
+  -T, --trace         Trace: Log vars, requests and responses after each step
+  -v, --version       Show version
+  -w, --watch         Watch the Swagger files and rerun tests on changes
+```
+
+
+## Monkey Testing
+
+The most basic usage of `got-swag` is monkey testing:
+Each GET endpoint of a service is validated using minimal variable
+input, if any, and the definitions from the services' Swagger file.
+The endpoints are requested with random authentication/variable combinations
+until one combination leads to a response status code less than 400.
+
+Just invoke got-swag on a URL with the `-m` switch:
+
+```
+got-swag http://petstore.swagger.io/v2/swagger.json -m
+```
+
+See [monkeystore.yaml](examples/monkeystore.yaml) for an example of input variables.
+
+
+## Custom Tests
+
+Additionally, `got-swag` allows to embed custom tests in Swagger files
+or separate test suites.
+The test steps are written in JS using a small domain-specific language.
+Every step is evaluated, even if a previous step failed.
+
+For example, see [petstore.yaml](examples/petstore.yaml) (embedded) and
+[yoda.yaml](examples/yoda.yaml) (separate).
+
+
+## Test Syntax Reference
+
+### [Assertions](https://nodejs.org/api/assert.html)
+
+- `ok( actual )`
+- `equal( actual, expected )`
+- `notEqual( actual, expected )`
+- `deepEqual( actual, expected )`
+- `notDeepEqual( actual, expected )`
+- `strictEqual( actual, expected )`
+- `notStrictEqual( actual, expected )`
+- `deepStrictEqual( actual, expected )`
+- `notDeepStrictEqual( actual, expected )`
+- `match( actualString, expectedPattern )`
+
+### Validation
+
+- `validate( data, schema )`
+  - Validate JSON data against a JSON schema
+  - If `data` or `schema` are omitted, the last response is validated against
+    the current operation's response schema
+
+### Requests
+
+- `request( options )`
+  - Requests the current endpoint
+  - `options` is optional, see [http](https://nodejs.org/api/http.html)
+  - `options.data` sets the request body
+- Shortcuts:
+  - `get( url, headers )`
+  - `post( url, data, headers )`
+  - `put( url, data, headers )`
+  - `delete( url, headers )`
+  - `options( url, headers )`
+  - `head( url, headers )`
+  - Use `null` for `url` to request the current endpoint
+  - `headers` are optional
+
+### Authentication
+
+- `auth( securityDefinitionId, credentials, scopes )`
+  - Authenticates against a security definition
+  - `scopes` are optional and inferred from the API if possible
+
+### Utility
+
+- `encodeURIComponent( s )` encodes a string for URI transmission
+- `log( value )` logs a value
+- `monkeyAuth()` tries to authenticate using known method/credentials
+- `monkeyGet()` tries to GET using known parameters
+
+### Variables
+
+- `vars`: Variables reusable for all tests
+  - You can write to `vars` in test steps, see example
+- `req`: Last request data
+- `res`: Last response data
+  - `res.status`: Integer response status code
+  - `res.headers`: Response headers
+  - `res.body`: String response body
+  - `res.json`: Parsed JSON response, if any
+- `api`: Complete Swagger API
+
+### Extension Syntax
+
+You can define extension Swagger files on top of existing Swagger files
+using the `'#/path': value` syntax.
+For reference, see [extended-petstore.yaml](examples/extended-petstore.yaml).
+
+
+## Programmatic Usage
+
+```js
+var gotSwag = require( 'got-swag' );
+
+// test api and report as JSON
+gotSwag.test( 'swag.yaml', 'vars.yaml' ).then( function ( report ) {
+  console.log( report );
+} );
+
+// describe mocha tests in current suite
+describe( 'My test suite', function () {
+  gotSwag.describe( 'swag.yaml', 'vars.yaml', { parent: this } );
+} );
+```
+
+
+## Notes
+
+- Currently, `got-swag` only supports JSON
+- The DSL is sandboxed using [vm](https://nodejs.org/api/vm.html)
+- If you see something like
+  `.../node_modules/got-swag/lib/validate.js:24 throw new Error( result.errors );`
+  in your console, it's a [Node.js Bug](https://github.com/nodejs/node/issues/7397)

bin/got-swag

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+var gotSwag = require( '../' );
+
+gotSwag.dispatch( process.argv.slice( 2 ) ).catch( function ( err ) {
+  // exit code 2 if an error occured
+  console.error( err.message );
+  process.exit( 2 );
+} );

examples/extended-petstore.yaml

@@ -0,0 +1,38 @@
+# Extension syntax example
+# got-swag examples/extended-petstore.yaml
+
+# import an existing swagger file into root
+'#/':
+  $ref: http://petstore.swagger.io/v2/swagger.json
+
+# set a new variable
+'#/x-vars/george':
+  id: 73
+  age: 6y
+  name: George
+# append spaces to have multiple actions on the same path
+'#/x-vars/george ':
+  # $assign extends the original object (shallow)
+  $assign:
+    cool: true
+# slahes must be written as double underscores!
+'#/paths/__pet__findByStatus/get/x-tests':
+  - description: Should find pets
+    steps:
+      - get( '/v2/pet/findByStatus?status=available' )
+      - log( res.json[ 0 ] )
+      - equal( res.status, 200 )
+      - ok( res.json.length > 0 )
+      - equal( typeof res.json[ 0 ].name, 'string' )
+      - validate()
+  - description: Should not find evil pets
+    steps:
+      - get( '/v2/pet/findByStatus?status=evil' )
+      - deepEqual( res.json, [] )
+      - validate()
+
+# special actions:
+# $assign will do a shallow extend
+# $merge will do a deep extend
+# $push will append to an array
+# $unshift will prepend to an array

examples/monkeystore.yaml

@@ -0,0 +1,17 @@
+# Monkey testing example
+# got-swag http://petstore.swagger.io/v2/swagger.json examples/monkeystore.yaml -m
+
+x-vars:
+  auth:
+    special:
+      key: special-key
+  monkey:
+    - status: available
+    - orderId: 3
+    - orderId: 9
+    - petId: 9
+  # the variable structure is arbitrary
+  # these usernames are also used by the monkey test
+  users:
+    - username: user1
+    - username: user2

examples/petstore.yaml

@@ -0,0 +1,87 @@
+# Custom tests example
+# got-swag examples/petstore.yaml examples/vars.yaml
+# The tests could be published by the service itself
+
+swagger: "2.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+host: petstore.swagger.io
+basePath: /v2
+schemes:
+  - http
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  /pet/findByStatus:
+    get:
+      summary: Finds pets by status
+      parameters:
+        - name: status
+          in: query
+          description: Status values that need to be considered for filter
+          required: false
+          type: array
+          items:
+            type: string
+      responses:
+        200:
+          description: An array of pets
+          schema:
+            $ref: '#/definitions/Pets'
+        default:
+          description: Unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+      x-tests:
+        - description: Should find pets
+          steps:
+            - get( '/v2/pet/findByStatus?status=available' )
+            - log( res.json[ 0 ] )
+            - equal( res.status, 200 )
+            - ok( res.json.length > 0 )
+            - equal( typeof res.json[ 0 ].name, 'string' )
+            - validate()
+        - description: Should not find evil pets
+          steps:
+            - get( '/v2/pet/findByStatus?status=evil' )
+            - deepEqual( res.json, [] )
+            - validate()
+definitions:
+  Pet:
+    required:
+      - name
+    properties:
+      id:
+        type: integer
+      category:
+        $ref: '#/definitions/Category'
+      name:
+        type: string
+      tag:
+        type: string
+  Pets:
+    type: array
+    items:
+      $ref: '#/definitions/Pet'
+
+  Category:
+    properties:
+      id:
+        type: integer
+      name:
+        type: string
+  Error:
+    required:
+      - code
+      - message
+    properties:
+      code:
+        type: integer
+        format: int32
+      message:
+        type: string

examples/sentiments.yaml

@@ -0,0 +1,27 @@
+# POST example
+# got-swag examples/sentiments.yaml examples/monkeystore.yaml -t 5000
+
+x-tests:
+
+  - description: Check sentiments of Texts
+    cases:
+      - text: You will learn how to speak like me someday. Oh wait.
+      - text: You have much to learn, my very young padawan.
+      - text: |
+          Death is a natural part of life.
+          Rejoice for those around you who transform into the Force.
+          Do not mourn them.
+          Do not miss them.
+          Attachment leads to jealously.
+          That is the shadow of greed.
+    steps:
+      - auth( 'mashape', vars.auth.mashape )
+      - post( 'https://text-sentiment.p.mashape.com/analyze', data )
+      - log( res.json.pos )
+      - ok( res.json.pos > 0 )
+
+securityDefinitions:
+  mashape:
+    type: apiKey
+    in: header
+    name: X-Mashape-Key

examples/vars.yaml

@@ -0,0 +1,6 @@
+x-vars:
+  auth:
+    mashape:
+      key: 1MIoJYAcmjmshMFpTOMIGSA0sMRRp1Rx6qSjsnLxdisqoTcYJc
+    petstore:
+      key: special-key