- Introduction
- Rationale
- Usage
- Specification format
- Gherkin source files
- featurebook.json
- .featurebookignore
- SUMMARY.md
- Public API
- Development environment
- Contributing
- Project roadmap
- License
FeatureBook is a command line tool (and Node.js library) for generating beautiful system specifications from Gherkin source files. Here are the example specifications you can play with.
Even in 2017, there are development teams that don't know how to apply Scrum or some other Agile methodology in day-to-day business. Believe it or not but that's the matter of fact. Doing just daily meetings at 9 or 10 a.m. doesn't really mean that you're in the Agile mode. With business analysts or other business folks it's even worse. Most of them haven't heard the buzzwords Scrum or Agile. Therefore, it's not surprising that so many people undervalue specifying unambiguously what the system is supposed to do. Instead, we are given 200 pages Microsoft Word documents that, after a short while, become a maintenance nightmare and complete mess to read and understand.
FeatureBook is here to help you creating living documentation from Gherkin source files (suitable for DEV or QA guys) and publish it in a format accessible for people who may not know how to work with source control systems or who are not interested in seeing all of the source code. We bring the fun back into writing documentation!
What's more, the authors of FeatureBook are ready to help you writing system specification for real-life complex systems and applications. If it's not a top secret mission critical beast, feel free to submit an issue where we can discuss the details publicly. Otherwise let's meet in person in Warsaw, Poland. If you buy the tickets and we like the destination, we'll fly over and do the training for you and your team! (Especially we're looking forward to seeing Albania one day.) The outcome would be a FeatureBook tailored for your system.
Before installing FeatureBook, you will need the following:
- Node.js v4.x+
- npm (which comes bundled with Node) v2.1.0+
FeatureBook can be installed (or updated if it's already installed) from npm:
$ npm install -g featurebook
You can serve the current directory as a system specification:
$ featurebook serve --port 3000
Or simply build a PDF document:
$ featurebook pdf
To list all available commands and options:
$ featurebook --help
Usage: featurebook [options] [command]
Commands:
serve [options] [spec-dir] serve <spec-dir> as a system specification
pdf [options] [spec-dir] build the specification PDF document
html [options] [spec-dir] build the specification HTML document
Options:
-h, --help output usage information
-V, --version output the version number
To display help for a given command:
$ featurebook serve --help
Usage: serve [options] [spec-dir]
serve <spec-dir> as a system specification
Options:
-h, --help output usage information
-p, --port <port> port on which to listen to (defaults to 3000)
FeatureBook can be used with Gulp to generate a system specification as part of your continuous integration process.
A system specification is a directory containing:
- Gherkin source files organized into subdirectories
- The
assets
directory for images and videos that you can refer to from within the Gherkin source files as well as summary descriptors - Optional directory descriptors (
SUMMARY.md
) - An optional specification descriptor (
featurebook.json
)
|-- assets
| `-- images
| |-- analytics.png
| |-- lock_box.jpg
| `-- time_tracking.png
|-- administrating
| |-- employee_management.feature
| |-- project_management.feature
| `-- reporting.feature
|-- authenticating
| |-- admin_authentication.feature
| |-- employee_authentication.feature
| `-- SUMMARY.md
|-- non_functional
| `-- service_level_agreement.feature
|-- time_tracking.feature
|-- unparsable.feature
|-- SUMMARY.md
|-- featurebook.json
`-- .featurebookignore
There are a few conventions:
- A single Gherkin source file contains a description of a single feature.
- Source files have the
.feature
extension. - A feature name displayed in the navigation tree is inferred from the corresponding Gherkin file name, i.e. it's
a titleized base file name. For example,
service_level_agreement.feature
becomes Service level agreement. - You can use Markdown in Gherkin source files and directory descriptors (
SUMMARY.md
). The FeatureBook's Markdown parser recognizes thefeature://
andasset://
URL schemas so you can cross reference features and images contained in theassets
directory.
A Gherkin source file usually looks like this:
# language: en
# featurebookDisplayName: Service Level Agreement Overwrite
Feature: Service level agreement
Keeping our customers happy is really important. This is why we cater for
the highest availabilty.
![Analytics](asset://assets/images/analytics.png)
Scenario: New account creation
Given there are "100000" users registered on the system
When I create a new account
Then I should be taken to my dashboard within "5" ms
Scenario: Homepage page access
Given "1000" users are hitting the homepage simultaneously
Then each user should get a response within "2" ms
NB Featurebook recognizes the
featurebookDisplayName
comment to overwrite the name of a given feature which is displayed in the navigation tree.
The featurebook.json
contains specification's metadata, i.e. title, version, authors, and contributors.
{
"title": "Time Tracking",
"version": "1.0.0",
"authors": [
{
"firstName": "Richard",
"lastName": "Feynman",
"email": "[email protected]"
}
],
"contributors": [
{
"firstName": "Isaac",
"lastName": "Newton",
"email": "[email protected]"
}
]
}
A .featurebookignore
file specifies files that featurebook should ignore when traversing the specification directory.
For example, a typical SpecFlow project contains .feature
and auto-generated .feature.cs
files. To ignore the auto-generated files you can create .featurebookignore
with the following content:
# Ignore auto-generated C# code
*.cs
Note that featurebook implicitly adds the following patterns to the ignore list:
featurebook.json
,SUMMARY.md
,.featurebookignore
,assets
,dist
,.git
.
Typically, this is a textual description of features and scenarios contained in a given directory. The summary of the root specification directory should give a general ovierview and reading guidelines.
# Time Tracking
Best time tracking system for a small business. A simple online timer with a powerful timesheet calculator.
![Time tracking](asset://assets/images/time_tracking.png)
It is recommended to start reading the [admin authentication](feature://authenticating/admin_authentication.feature) feature.
Most of the time, you will be using FeatureBook directly from command line. You can, however, call FeatureBook programmatically from your Node.js module. Here is the public API.
To try out the latest development version clone this repository and link the featurebook package:
$ git clone https://github.com/SOFTWARE-CLINIC/featurebook.git && cd featurebook && npm link
You wanna contribute to FeatureBook? That is truly great! Here are some tips to get you started.
FeatureBook started as a command line tool based on Node.js. However this requires project managers and other non-tech
people to install node
and npm
and have basic understanding of those command line tools. Even if it's not very complicated
to install node
I decided to distribute FeatureBook as as cross-platform desktop application
based on electron. You can find the corresponding repository here
featurebook-desktop.
Code is under the MIT.