1 | FBP Network Protocol
|
2 | ====================
|
3 |
|
4 | Tests, schemas, and specifications for the Flow Based Programming Network Protocol.
|
5 |
|
6 | You can find a built version of the specification at [flowbased.github.io/fbp-protocol](http://flowbased.github.io/fbp-protocol/).
|
7 |
|
8 | The included test suite provide an easy way for developers to test their runtimes for compatibility with the protocol.
|
9 | Also included are files useful to runtime developers, such as message schemas.
|
10 |
|
11 | The test suite currently works for runtimes based on the Websocket transport.
|
12 |
|
13 | Installing the test suite
|
14 | -------------------------
|
15 |
|
16 | 1. Install Node.js using their [installer](http://nodejs.org/download/) or a [package manager](https://github.com/joyent/node/wiki/installing-node.js-via-package-manager)
|
17 |
|
18 | 2. Install this package.
|
19 |
|
20 | You can install it within your project, which will place the executables in `./node_modules/.bin`:
|
21 |
|
22 | ```
|
23 | cd /path/to/my/project
|
24 | npm install fbp-protocol
|
25 | ```
|
26 |
|
27 | Or globally, which should put executables on the `PATH`:
|
28 |
|
29 | ```
|
30 | sudo npm install fbp-protocol -g
|
31 | ```
|
32 |
|
33 |
|
34 | Testing a runtime
|
35 | -----------------
|
36 |
|
37 | 1. Before you can run the tests (successfully), your runtime needs to provide a few basic components. These are currently `Repeat`, `Drop`, and `Output`.
|
38 |
|
39 | By default, the tests will look for these in the "core" collection, however this is configurable. For example, if you want to implement these components as a one-off just for the tests, you can place them in a "tests" collection and pass `--collection tests` to `fbp-init`.
|
40 |
|
41 | 2. Use `fbp-init` to save a configuration file for your runtime into the current directory (keep in mind that if you used the local install method, you'll need to run `./node_modules/.bin/fbp-init`). Use `fbp-init -h` to see the available options and their defaults.
|
42 |
|
43 | Here's an example:
|
44 |
|
45 | ```
|
46 | fbp-init --name protoflo --port 3569 --command "python -m protoflo runtime"
|
47 | ```
|
48 |
|
49 | This will produce the file `fbp-protocol.json` in the current directory. Its location within your project is not important, but it needs to be in the current working directory when you run the tests.
|
50 |
|
51 | 3. Run the tests:
|
52 |
|
53 | ```
|
54 | fbp-test
|
55 | ```
|
56 |
|
57 | If the runtime execution requires a `secret` to be sent, define it using the `FBP_PROTOCOL_SECRET` environment variable.
|
58 |
|
59 | Examples
|
60 | --------
|
61 |
|
62 | A Node.js package using grunt: https://github.com/chadrik/noflo-runtime-websocket/tree/fbp-protocol
|
63 |
|
64 |
|
65 | Contributing
|
66 | ------------
|
67 |
|
68 | JSON schemas are built from YAML schemas in schema/yaml. Improvements and
|
69 | additions to the schemas should be added there. The JSON schemas use
|
70 | [json-schema](http://json-schema.org/) to validate protocol messages. To run tests,
|
71 | use grunt test, which will run unit tests for the schemas and fbp-test.
|
72 | To build the schemas after updating the YAML files, run grunt build, which will
|
73 | create the JSON schemas, put them together for easy usage in schema/schemas.js,
|
74 | and update the docs with the latest schema definitions.
|
75 |
|
76 |
|
77 | TODO
|
78 | ----
|
79 | - handle `fbp-test -h`
|
80 | - capture server output to a log
|
81 | - isolate tests, so that one failure does not cause subsequent tests to fail
|
82 | - don't test capabilities that the runtime does not claim to support (as returned by `getruntime`)
|
83 | - add more tests:
|
84 | - `getsource` / `source`
|
85 | - topology restrictions
|
86 | - capturing output
|
87 | - existing tests from other projects:
|
88 | - https://github.com/jonnor/imgflo/blob/master/spec/websocket.coffee
|
89 | - https://github.com/jonnor/sndflo/blob/master/spec/runtime.coffee
|
90 | - https://github.com/jonnor/javafbp-runtime/blob/master/spec/protocol.coffee
|
91 | - https://github.com/microflo/microflo/blob/master/test/websocketapi.js
|
92 | - add examples (https://github.com/flowbased/protocol-examples)
|
93 | - add tests for `fpb-test`
|
94 | - add separate, optional tests for "classical" or "noflo" behaviors
|
95 | - use library for more flexible json comparison?
|
96 | - [joi](https://github.com/hapijs/joi)
|
97 | - [chai-json-schema](http://chaijs.com/plugins/chai-json-schema)
|
98 | - dynamically build tests based on sidecar json command / response files?
|
99 | - validate options read from `fbp-config.json`
|
100 | - make `fbp-init` prompt-based?
|
101 | - allow `fbp-test /path/to/fbp-config.json`
|
102 | - make `init` and `test` subcommands of a `fbp` command?
|
103 |
|
\ | No newline at end of file |