bdd-docs v2.0.1

How do we generate pages out of feature files

We use gatsby-source-filesystem in gatsby-config.js to create File nodes from our feature files. They can then be used with gatsby-transformer-gherkin to query contents of files with gherkin syntax.

The code for creating feature pages with createPage function lives in gatsby-node.js, and it is using FeaturePage as the template.

To highlight the code we use Prism.js and pass the formatted code directly to the template.

Symlinks

Most of the .feature files in src/sites/marvel3/src/features are symlinked, which means they point to the original files that live in corresponding apps and packages. If you update any of the files in the symlinked folders, they should also update in the original location (and vice versa).

When updating feature files, avoid renaming the symlinked folders (easy to spot, as they have an arrow next to folder name in VS Code) or moving any of the feature files out of them, because it can affect our tests. Having said that, you can create folders within the symlinked folders, update their contents and put feature files in them.

How to create a symlink

Run the following command from the features folder in src/sites/marvel3/src/features:

ln -s ../../../../packages/prototype-viewer/src/features prototype-viewer-features

where the first argument is a path to the folder you want to symlink and the second argument is the name of your symlink.

File metadata

In order for a feature file to be converted into a page, it needs to have # Parent: and # Sidebar Link: comments, which act as the file's metadata. # Parent: is used as the category for the file, and # Sidebar Link: is the name you will see in the sidebar. In the below example, Archiving project and Unarchiving project are pages with an Archive parent.

--- Archive
------ Archiving project
------ Unarchiving project

Note: # Sidebar Link: and # Parent are also used for generating page urls.

Another two pieces of metadata you can use (although they are optional), are # Title: and # Description. They are a great way to provide more context to your feature pages.

BDD metadata VS Code snippet

https://share.getcloudapp.com/qGudWGJ5

You can use VS Code snippet feature to create a snippet for quickly adding metadata to your files (see attached video). To add it, follow the below steps:

1. Press shift + cmd + p to open the commands menu
2. Search for 'snippets', you should see something like: Preferences: Configure User Snippets
3. Once you've selected that option, search for 'feature'. This will allow you to add a snippet for any files with .feature extension
4. Add the following snippet to the json file

	"Add BDD Meta data": {
		"prefix": "bdd-meta",
		"body": [
			"# Title: ",
			"# Description: ",
			"# Parent: ",
			"# Sidebar Link: "
		],
		"description": "Add BDD meta data"
	}

5. You should now be able to type bdd-metadata in your feature files to expand the snippet.