Setup and Configure

Once you have installed SpecSync for Jira tool, you need to configure it. This means you have to create a SpecSync configuration file (specsync.json) that contains the Jira project connection details and other synchronization settings.

Step 1: Define feature file sets

SpecSync has to be configured for every feature file set. Feature file set is a folder that contains feature files that you want to synchronize as one batch.

Feature file set is a term introduced by SpecSync to denote the set of feature files that belong together in a platform independent way. Earlier we used the term project folder, but it was misleading, because people might call different things as "project" on .NET, Java and node.js platforms and also it could be confused with Jira projects.

If you use SpecSync with SpecFlow, the Visual Studio projects configured with SpecFlow are the feature file sets.

For other BDD tools, like Cucumber, usually the features folder(s) are set as feature file sets.

Each feature file set will have its own SpecSync configuration file (specsync.json). For projects with multiple feature file sets, you can use hierarchical configuration files as well.

It is up to you how you define your feature file sets. The following table contains a few usual setup variations.

Platform & tool	Feature file set (location of specsync.json)
.NET solution with a single SpecFlow project	The SpecFlow project folder (e.g. MyProject.Specs)
.NET solution with multiple SpecFlow projects	Each SpecFlow project folder (e.g. MyProject.BackOffice.Specs and MyProject.ClientApp.Specs)
node.js app with Cucumber.js	The parent folder of the features folder (e.g. /src/test/)
node.js app with multiple feature file sets	The parent folders of the features folders (e.g. /src/test/backoffice/ and /src/test/clientapp/)
Java app with Cucumber Java	The parent folder of the features folder (e.g. /src/test/resources/)

You can also consider setting the features folder itself as a root of the feature file set (e.g. /src/test/resources/features/ instead of /src/test/resources/).

The feature file sets of your project and be changed later by moving the specysnc.json configuration file to a different location.

Step 2: Initialize configuration file using the SpecSync init command

The easiest way to initialize the configuration file and configure the most important settings is to use the SpecSync init command. To use the command open a command window or bash shell and change the current directory to the root folder of the feature file set and invoke the following command.

.NET Core tool

dotnet specsync init

.NET Console App

SpecSync4Jira.cmd init

Native binaries

<EXTRACTED-SPECSYNC-FOLDER>/SpecSync4Jira init

The init command will ask a few questions in order the setup the connection to the Jira project, like the server URL and the authentication details. If you are unsure about what is exactly your Jira server URL, please check the What is my Jira server URL page. You can fine more information about the authentication options in the Jira authentication options page.

It is recommended to let the init command test the authentication to the Jira project to make sure the connection is configured properly.

Step 3: Review SpecSync features and extend configuration settings

The init command configures the settings that are enough for the first synchronization. SpecSync comes with useful default values for all settings, but you can still review the SpecSync features and extend the configuration if you need to. It is recommended to think about whether you would like to exclude any scenarios from the synchronization.

Features

Configuration reference

Step 4: Verify setup by synchronizing scenarios

When the SpecSync configuration file is complete, you can perform the first synchronization task and verify the results using the push command.

For larger feature file sets it is recommended to make the first synchronization only for a few selected scenarios tagged with a particular tag. You can even temporarily tag a few scenarios in order to test the synchronization. In our example we assume that the selected scenarios are tagged with @specsync_test.

To use the command open a command window or bash shell and change the current directory to the root folder of the feature file set and invoke the following command. For all command line option of the push command, please check the command line reference.

.NET Core tool

dotnet specsync push --tagFilter @specsync_test

.NET Console App

SpecSync4Jira.cmd push --tagFilter @specsync_test

Native binaries

<EXTRACTED-SPECSYNC-FOLDER>/SpecSync4Jira push --tagFilter @specsync_test

The synchronization should run successfully and SpecSync should create Test Cases in Jira for the selected scenarios and link to them using a tag.

In case of errors, you can retry the synchronization with an additional --verbose option that displays additional diagnostic information. If this does not help, please check the Troubleshooting page or contact SpecSync Support.