SpecSync for Azure DevOps

https://github.com/specsolutions/specsync-for-tfs-documentation
Admin
SpecSync for Azure DevOps integrates BDD scenarios with Azure DevOps Test Cases and publishes test...
Tokens:128,273
Snippets:391
Trust Score:7.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### SpecSync Configuration File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

An example of the 'specsync.json' configuration file after basic setup. It includes the Azure DevOps project URL, user credentials, and specifies the local feature file source directory.

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",

  // See configuration options and samples at http://speclink.me/specsyncconfig.

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator",
    "user": "52yny........................................ycsetda"
  },
  "local": {
    "featureFileSource": {
      "type": "folder",
      "folder": "test/features"
    }
  }
}
```

--------------------------------

### SpecSync Configuration File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

An example of the 'specsync.json' configuration file, showing the schema and connection details for an Azure DevOps project.

```json
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",

  // See configuration options and samples at http://speclink.me/specsyncconfig.

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator",
    "user": "52yny........................................ycsetda"
  }
}
```

--------------------------------

### Install SpecSync as a Local .NET Core Tool

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Installs the SpecSync.AzureDevOps package as a local .NET Core tool within the SpecFlow project directory.

```bash
cd MyCalculator.Specs
dotnet tool install SpecSync.AzureDevOps
```

--------------------------------

### SpecSync for Azure DevOps - Getting Started

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/SUMMARY.md

Guides on how to get started with SpecSync for Azure DevOps, with specific instructions for SpecFlow and other Gherkin-based BDD tools like Cucumber.

```markdown
* [Getting started using SpecFlow](getting-started/getting-started-specflow.md)
* [Getting started using Cucumber or other Gherkin-based BDD tool](getting-started/getting-started-cucumber.md)
```

--------------------------------

### Initialize .NET Core Tool Manifest

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Initializes the .NET Core tool manifest in the current directory, which is required before installing local .NET Core tools.

```bash
dotnet new tool-manifest
```

--------------------------------

### SpecSync for Azure DevOps - Installation and Setup

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/SUMMARY.md

Details on how to install and set up SpecSync for Azure DevOps, covering various installation methods like .NET tool, .NET Console App, native binaries, and Docker.

```markdown
* [Install as .NET tool](installation/dotnet-core-tool.md)
* [Install as .NET Console App](installation/dotnet-console.md)
* [Install as native binaries for Linux or macOS](installation/native-binaries.md)
* [Install as Docker image](installation/docker-image.md)
* [Setup and Configure](installation/setup-and-configure.md)
```

--------------------------------

### Display SpecSync Version

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Invokes SpecSync using the 'dotnet specsync' command to display the installed version of the tool.

```bash
dotnet specsync version
```

--------------------------------

### SpecSync CLI Examples

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/README.md

Provides examples of common SpecSync command-line interface (CLI) operations, including displaying the version, getting help for specific commands, and pushing synchronization changes while logging output to a file.

```text
dotnet specsync version
```

```text
dotnet specsync help push
```

```text
dotnet specsync push --log log.txt
```

--------------------------------

### Example Scenario Tagging

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Demonstrates how SpecSync modifies SpecFlow feature files by adding '@tc:...' tags to scenarios and scenario outlines, establishing a link between the scenario and its corresponding Azure DevOps test case.

```text
@tc:1234
@important
Scenario: Add two positive numbers
```

--------------------------------

### SpecSync Push Command

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Executes the SpecSync push command to synchronize SpecFlow scenarios with Azure DevOps test cases. This command initiates the linking process and requires authentication if credentials are not pre-configured.

```bash
dotnet specsync push
```

--------------------------------

### Initialize SpecSync Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Initializes the SpecSync configuration in the repository root, creating a 'specsync.json' file. This command prompts for Azure DevOps project URL and authentication credentials.

```bash
dotnet specsync init
```

--------------------------------

### Synchronize Scenario Update

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

Demonstrates updating a scenario's title and steps, then synchronizing these changes using the SpecSync4AzureDevOps push command.

```text
@tc:1234
Scenario: Multiply two positive numbers
  Given I have entered the following numbers
    | number |
    | 29     |
    | 13     |
  When I choose multiply
  Then the result should be 377
```

```text
$SPECSYNC_DIR/SpecSync4AzureDevOps push
```

--------------------------------

### SpecSync4AzureDevOps.cmd Script Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-console.md

A sample Windows command script to easily execute the SpecSync .NET Console App by specifying the version and forwarding all command line parameters. This script assumes the package is installed in the global NuGet packages folder.

```bash
@REM Executing SpecSync .NET Console App by forwarding all command line parameters
@REM Note: the version number has to be updated after a SpecSync version upgrade
SET SPECSYNC_VERSION=3.3.8
%HOMEPATH%\.nuget\packages\SpecSync.AzureDevOps.Console\%SPECSYNC_VERSION%\tools\SpecSync4AzureDevOps.exe %*

```

--------------------------------

### Initialize SpecSync Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

Initializes the SpecSync configuration in the local repository root, creating the 'specsync.json' file. This command prompts for Azure DevOps project URL and authentication credentials.

```text
$SPECSYNC_DIR/SpecSync4AzureDevOps init
```

--------------------------------

### SpecSync Configuration File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-on-osxlinux-page.md

An example of the `specsync.json` configuration file, showing typical 'remote' and 'local' sections for synchronizing Gherkin scenarios.

```json
{
  "remote": {
    "url": "https://your.alm.tool/api",
    "username": "your_username",
    "password": "your_password"
  },
  "local": {
    "path": "./features"
  }
}
```

--------------------------------

### Synchronize Scenario Update

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Demonstrates updating a SpecFlow scenario and pushing the changes using the SpecSync CLI. It shows how to modify scenario titles, steps, and expected results, and then synchronize these changes.

```text
@tc:1234
Scenario: Multiply two positive numbers
  Given I have entered the following numbers
        | number |
        | 29     |
        | 13     |
  When I choose multiply
  Then the result should be 377
```

```dotnetcli
dotnet specsync push
```

--------------------------------

### SpecSync Init Command Examples

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/init-command.md

Demonstrates how to initialize SpecSync configuration interactively or for a specific Azure DevOps project.

```text
dotnet specsync init
```

```text
dotnet specsync init -p https://specsyncdemo.visualstudio.com/MyCalculator
```

--------------------------------

### Push SpecSync Scenarios to Azure DevOps

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/setup-and-configure.md

Synchronizes scenarios to Azure DevOps Test Cases using the 'push' command. Supports filtering by tags to manage large feature file sets. Includes examples for .NET Core tool, .NET Console App, and native binaries.

```bash
dotnet specsync push --tagFilter @specsync_test
```

```cmd
SpecSync4AzureDevOps.cmd push --tagFilter @specsync_test
```

```bash
<EXTRACTED-SPECSYNC-FOLDER>/SpecSync4AzureDevOps push --tagFilter @specsync_test
```

--------------------------------

### Invoke SpecSync Push Command

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

This command initiates the synchronization process, pushing scenarios from the local project to Azure DevOps. Ensure you are in the project root folder before execution. Authentication may be required if credentials are not pre-configured.

```text
$SPECSYNC_DIR/SpecSync4AzureDevOps push
```

--------------------------------

### Publish Test Results to Azure DevOps

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Publishes test results from a specified TRX file to Azure DevOps using the SpecSync CLI. This command analyzes the results and associates them with corresponding Test Cases.

```bash
dotnet specsync publish-test-results --testResultFile TestResults\testresult.trx
```

--------------------------------

### Execute Tests with TRX Logger

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Executes SpecFlow tests and generates a test result file in TRX format. This file is used by SpecSync to publish results to Azure DevOps.

```bash
dotnet test --logger trx;logfilename=testresult.trx
```

--------------------------------

### toolSettings Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-toolsettings.md

Provides an example of the toolSettings configuration block, showcasing available options for license path, statistics disabling, output level, parent configuration, and ignoring parent configuration.

```javascript
{
  "toolSettings": {
    "licensePath": "specsync.lic",
    "disableStats": false,
    "outputLevel": "normal",
    "parentConfig": "specsync-common.json",
    "ignoreParentConfig": false
  }
}
```

--------------------------------

### Verify SpecSync Installation

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Checks if SpecSync has been installed correctly by displaying its version. This command confirms that SpecSync is accessible and ready for use.

```bash
dotnet specsync version
```

--------------------------------

### Push Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-push.md

An example of the push configuration section within the synchronization settings, showing the conflictResolution option.

```javascript
{
  ...
  "synchronization": {
    ...
    "push": {
      "conflictResolution": "interactive"
    },
    ...
  },
  ...
```

--------------------------------

### Example Scenario Tagging

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

Demonstrates how SpecSync adds a '@tc:...' tag to scenarios in feature files to link them to corresponding test cases in Azure DevOps. This tagging is crucial for maintaining the connection between your Gherkin scenarios and your test management system.

```text
@tc:1234
@important
Scenario: Add two positive numbers
```

--------------------------------

### Minimal SpecSync Configuration File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/general-features/configuration-file.md

A basic example of a specsync.json configuration file, demonstrating the schema and remote project URL settings. This file is used to configure SpecSync synchronization tasks.

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator"
  }
}
```

--------------------------------

### Verify SpecSync Installation (Zip Package)

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-console.md

Verifies the SpecSync installation from a downloaded zip package by executing the SpecSync4AzureDevOps.exe with the 'version' argument. This command should be run from the project folder.

```bash
<EXTRACTED-SPECSYNC-FOLDER>\tools\SpecSync4AzureDevOps.exe version
```

--------------------------------

### Iteration Path Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-iterationpath.md

Example of the iterationPath configuration within the synchronization section, showing the 'mode' and 'value' settings.

```javascript
{
  "synchronization": {
    "iterationPath": {
      "mode": "setOnLink",
      "value": "\\Iteration1"
    }
  }
}
```

--------------------------------

### Verify SpecSync Installation (NuGet)

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-console.md

Checks if the SpecSync installation is successful by querying the installed version using the SpecSync4AzureDevOps.cmd script.

```bash
SpecSync4AzureDevOps.cmd version
```

--------------------------------

### Publish Test Results Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-publishtestresults.md

An example of the 'publishTestResults' configuration section, demonstrating common settings for publishing test results.

```javascript
{
  "publishTestResults": {
    "testResult": {
      "filePath": "test-result.trx"
    },
    "treatInconclusiveAs": "Failed",
    "testConfiguration": {
      "name": "Windows 10"
    },
    "testRunSettings": {
      "name": "Acceptance test results"
    },
    "testResultSettings": {
      "comment": "BDD results"
    }
  }
}
```

--------------------------------

### Verify SpecSync Installation

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/native-binaries.md

Checks the installed SpecSync version by invoking the executable with the 'version' command.

```bash
<EXTRACTED-SPECSYNC-FOLDER>/SpecSync4AzureDevOps version
```

--------------------------------

### Publish Cucumber Java Test Results

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

Publishes test results from a Cucumber Java JUnit XML file to Azure DevOps. This command analyzes the result file and associates the results with corresponding test cases, creating a Test Run in Azure DevOps.

```bash
dotnet specsync publish-test-results --testResultFile mytestresult.xml 
  --testResultFileFormat cucumberJavaJUnitXml
```

--------------------------------

### Install SpecSync as a .NET Local Tool

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Installs the latest version of SpecSync from NuGet.org as a local tool for the project. This command downloads and sets up the SpecSync.AzureDevOps package.

```bash
dotnet tool install SpecSync.AzureDevOps
```

--------------------------------

### Install SpecSync NuGet Package

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-console.md

Installs the SpecSync.AzureDevOps.Console NuGet package into a .NET project using the Package Manager Console.

```csharp
Install-Package SpecSync.AzureDevOps.Console
```

--------------------------------

### Configure Test Suite Synchronization

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-cucumber.md

Shows how to configure SpecSync to add synchronized test cases to a specific test suite in Azure DevOps by specifying the test suite name in the specsync.json configuration file.

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",

  // See configuration options and samples at http://speclink.me/specsyncconfig.

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator",
    "user": "52yny4a......................................ycsetda",
    "testSuite": {
      "name": "BDD Scenarios"
    }
  },
  //[...]
}
```

```text
$SPECSYNC_DIR/SpecSync4AzureDevOps push
```

--------------------------------

### User-Specific Configuration Example (specsync.json)

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/general-features/hierarchical-configuration-files.md

This example demonstrates a user-specific configuration file for SpecSync. It includes settings for the license file path and authentication credentials for Azure DevOps projects.

```javascript
{
  "$schema": "https://schemas.specsolutions.eu/specsync-user-config-latest.json",

  "toolSettings": {
    "licensePath": "specsync.lic" // in the same folder as the user-specific setting
  },
  "knownRemotes": [
    {
      "projectUrl": "https://dev.azure.com/myorg/*",
      "user": "g2x.....................ac2vx57i4a"
    },
    {
      "projectUrl": "https://dev.azure.com/otherorg/OtherProject",
      "user": "y6s.....................ksuc7tsts"
    }
  ]
}
```

--------------------------------

### Dockerfile for SpecSync

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-inside-a-docker-container.md

Creates a Docker image from ubuntu:22.04, installs SpecSync native binaries, and exposes the SpecSync command-line tool as the default entry point. It installs wget and unzip, downloads the specified SpecSync version, and sets the working directory and entry point.

```text
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    wget \
    unzip \
    && rm -rf /var/lib/apt/lists/*

ARG SPECSYNC_VERSION=3.3.8
ARG LOCAL_DIR=/local

WORKDIR /specsync

RUN wget -qO specsync.zip https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.${SPECSYNC_VERSION}-linux-x64.zip \
  && ( unzip -q specsync.zip || [ $? -le 1 ] ) \
  && rm specsync.zip \
  && bash -c "chmod +x ./SpecSync4AzureDevOps"

# Enable detection of running in a container
ENV DOTNET_RUNNING_IN_CONTAINER=true

WORKDIR ${LOCAL_DIR}

ENTRYPOINT [ "/specsync/SpecSync4AzureDevOps" ]
```

--------------------------------

### areaPath Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-areapath.md

An example of the areaPath configuration within the synchronization settings. This shows how to specify the mode and value for updating the area path.

```javascript
{
  "synchronization": {
    "areaPath": {
      "mode": "setOnLink",
      "value": "\\MyArea"
    }
  }
}
```

--------------------------------

### SpecSync Pull Command Examples

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/pull-command.md

Demonstrates various ways to use the 'dotnet specsync pull' command with different options for filtering and authentication.

```text
dotnet specsync pull
```

```text
dotnet specsync pull --user 52yny...........................nycsetda
```

```text
dotnet specsync pull --tagFilter "@ordering and @backend"
```

```text
dotnet specsync pull --createOnly
```

--------------------------------

### SpecSync Synchronization Command Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/how-to-define-the-local-feature-set-to-be-synchronized.md

This command demonstrates how to initiate the synchronization process for the backend feature set by specifying the relevant configuration file. It assumes the command is run from the 'src' directory.

```bash
...src> dotnet specsync push specsync-backend.json
```

--------------------------------

### Attachments Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-attachments.md

An example of the JSON configuration for enabling and customizing file attachments in SpecSync. This includes enabling the feature, defining custom tag prefixes, and setting a base folder for attachments.

```javascript
{
  "synchronization": {
    "attachments": {
      "enabled": true,
      "tagPrefixes": [
        "wireframe",
        "specification"
      ],
      "baseFolder": "resources/files"
    }
  }
}
```

--------------------------------

### Set Executable Permissions

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/native-binaries.md

Sets the executable permission for the SpecSync4AzureDevOps binary on Linux/macOS.

```bash
chmod +x SpecSync4AzureDevOps
```

--------------------------------

### Minimal SpecSync Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/README.md

A basic example of a SpecSync JSON configuration file, including essential settings like schema and compatibilityVersion.

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync-config-latest.json",
  "compatibilityVersion": 3.3,

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator"
  }
}
```

--------------------------------

### SpecSync Backend Specific Configuration Example (Root Folder)

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/how-to-define-the-local-feature-set-to-be-synchronized.md

Example of a SpecSync configuration file (`specsync-backend.json`) placed in the root folder, specifying the parent configuration and the local feature file source for backend scenarios.

```json
{
  "toolSettings": {
    "parentConfig": "specsync-parent.json"
  },
  "local": {
    "featureFileSource": {
      "type": "folder",
      "folder": "backend/features"
    }
  },
  "remote": {
    "testSuite": {
      "name": "Backend BDD Scenarios"
    }
  }
}
```

--------------------------------

### Initialize SpecSync Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/setup-and-configure.md

Commands to initialize the SpecSync configuration file (`specsync.json`) for different .NET environments and native binaries. This command prompts for Azure DevOps project connection details and authentication.

```.NET Core tool
dotnet specsync init
```

```.NET Console App
SpecSync4AzureDevOps.cmd init
```

```Native binaries
<EXTRACTED-SPECSYNC-FOLDER>/SpecSync4AzureDevOps init
```

--------------------------------

### SpecSync Parent Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/how-to-define-the-local-feature-set-to-be-synchronized.md

Example of a parent SpecSync configuration file (`specsync.json` or `specsync-parent.json`) containing common settings like repository URL and synchronization automation.

```json
{
  "remote": { // common target URL
    "projectUrl": "https://dev.azure.com/myorganization/MyProject"
  },
  "synchronization": { // some common synchronization settings
    "automation": {
      "enabled": true
    }
  }
}
```

--------------------------------

### Initialize .NET Local Tool Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Creates the necessary configuration file for .NET local tools if it doesn't exist. This command generates a 'dotnet-tools.json' file under the '.config' directory, which should be added to source control.

```bash
dotnet new tool-manifest
```

--------------------------------

### Upgrade SpecSync to Latest Version

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Upgrades the SpecSync .NET tool to the latest available release version using the dotnet CLI.

```bash
dotnet tool update SpecSync.AzureDevOps
```

--------------------------------

### Register SpecSync Plugin

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/general-features/specsync-plugins.md

Example of registering a SpecSync plugin with its package ID, version, and custom parameters in the specsync.json configuration file.

```javascript
{
  "toolSettings": {
    "plugins": [
      {
        "packageId": "MySpecSyncPlugin",
        "packageVersion": "1.0.0",
        "parameters": {
          "pluginParameter1":  "value1" 
        } 
      }
    ]
  }, 
  ...
}
```

--------------------------------

### SpecSync Re-link Command Examples

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/re-link-command.md

Examples demonstrating the usage of the 'specsync re-link' command for re-linking scenarios. Shows how to perform the operation automatically, for a specific clone operation ID, and in dry-run mode.

```text
dotnet specsync re-link
```

```text
dotnet specsync re-link --cloneOpId 42
```

```text
dotnet specsync re-link --dryRun
```

--------------------------------

### Install SpecSync with Official NuGet Source

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/contact/troubleshooting.md

Installs SpecSync as a .NET tool while explicitly using the official NuGet source to resolve 'Unable to find package' errors.

```bash
dotnet tool install SpecSync.AzureDevOps --add-source  https://api.nuget.org/v3/index.json --ignore-failed-sources
```

--------------------------------

### MsTest V1 Project Setup

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/test-result-publishing-features/support-for-azure-devops-test-plan-test-suite-based-test-execution.md

This section details the necessary project setup for legacy MsTest V1 projects to work with SpecSync's 'Use TestCase Data' feature. It emphasizes the correct assembly reference and warns against using newer NuGet packages.

```csharp
// Ensure your project has a reference to:
// Microsoft.VisualStudio.QualityTools.UnitTestFramework

// Do NOT use the following NuGet packages:
// MSTest.TestFramework, MSTest.TestAdapter
```

--------------------------------

### SpecSync Backend Specific Configuration Example (Per Folder)

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/how-to-define-the-local-feature-set-to-be-synchronized.md

Example of a SpecSync configuration file (`specsync.json`) located within a specific feature folder (e.g., `src/backend/features`) that defines backend-specific settings like the target test suite.

```json
{
  "remote": {
    "testSuite": {
      "name": "Backend BDD Scenarios"
    }
  }
}
```

--------------------------------

### Restore SpecSync for Project Collaborators and CI

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Restores all .NET local tools installed for the project, ensuring that other team members and build servers can use the same tools. This command is essential for maintaining consistency across development and deployment environments.

```bash
dotnet tool restore
```

--------------------------------

### fieldDefaults Customization Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-customizations.md

Demonstrates the 'fieldDefaults' customization, showing how to enable it and set default values for specific test case fields.

```javascript
{
  "synchronization": {
    "fieldUpdates": {
      "MyCompany.MyCustomField": {
        "value": "Default 1",
        "update": "onCreate"
      },
      "MyCompany.OtherCustomField": {
        "value": "Default 2",
        "update": "onCreate"
      }
    }
  },
}
```

--------------------------------

### Basic Link Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-links.md

This JavaScript snippet demonstrates a basic configuration for the 'links' section, specifying a single link type with a 'bug' tag prefix.

```javascript
{
  "synchronization": {
    "links": [
      {
        "tagPrefix": "bug"
      }
    ]
  }
}
```

--------------------------------

### SpecSync Command Line with PAT

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/general-features/server-authentication-options.md

Example of using SpecSync via the command line with a Personal Access Token (PAT) as the user credential.

```bash
path-to-specsync-package/tools/SpecSync4AzureDevOps.exe push --user "52yny...........................nycsetda"
```

--------------------------------

### SpecSync.Plugin.ScenarioOutlinePerExamplesTestCase

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/plugin-list.md

Synchronizes scenario outline examples blocks as individual test cases. This plugin is useful for managing complex scenario outlines.

```C#
SpecSync.Plugin.ScenarioOutlinePerExamplesTestCase
```

--------------------------------

### SpecSync Init Command Options

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/init-command.md

Details the available options for the SpecSync init command, including project URL, configuration file path, and verbosity.

```APIDOC
SpecSync Init Command:
  Initializes SpecSync configuration.

Options:
  -p, --projectUrl <PROJECT-URL>
    The project URL of the Azure DevOps project.
    Default: interactive prompt

  -c, --config <CONFIG-FILE-PATH>
    The full path or the folder of the configuration file being created.
    Default: specsync.json in the current folder

  -v, --verbose
    If specified, error messages and trace information will be displayed more in detail. Overrides toolSettings/outputLevel setting of the configuration file.
    Default: false

Description:
  Initializes SpecSync configuration by creating a `specsync.json` configuration file based on the settings provided for the interactive questions asked by the command. The command verifies the connection to the Azure DevOps project specified to avoid common authentication issues. For Personal Access Token (PAT) authentication, it offers to save authentication details to a user-specific configuration file.
```

--------------------------------

### SpecSync Customizations Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-customizations.md

Provides a comprehensive example of the 'customizations' section in the SpecSync configuration, showcasing various settings like fieldDefaults, customFieldUpdates, and tag management.

```javascript
{
  "customizations": {
    "fieldDefaults": {
      "enabled": true,
      "defaultValues": {
        "MyCompany.MyCustomField": "Default 1",
        "MyCompany.OtherCustomField": "Default 2"
      }
    },
    "customFieldUpdates": {
      "enabled": true,
      "updates": {
        "System.Description": "Synchronized from feature {feature-name}{br}{feature-description}"
      }
    },
    "ignoreTestCaseSteps": {
      "enabled": true,
      "ignoredPrefixes": [ "COMMENT" ]
    },
    "ignoreTestCaseTags": {
      "enabled": true,
      "tags": [ "mytag", "ado-tag*" ]
    },
    "ignoreNotSupportedLocalTags": {
      "enabled": true,
      "supportedTags": [ "@myTag", "@otherTag" ]
    }    
    "tagTextMapTransformation": {
      "enabled": true,
      "textMap": {
        "_": " "
      }
    },
    "multiSuitePublishTestResults": {
      "enabled": true,
      "testPlanId": 567,
      "suites": [
        "SuiteA",
        "SuiteB",
        "#3456"
      ],
      "includeSubSuites": true,
      "publishToRequirementBasedTestSuites": true,
      "linkTagPrefixes": [ "bug" ]
    },
    "resetTestCaseState": {
      "enabled": true,
      "state": "Ready",
      "condition": "@ready"
    },
    "addTestCasesToSuites": {
      "enabled": true,
      "testSuites": [
        {
          "name": "Important Logic",
          "condition": "@important and not @external"
        }
      ]
    },
    "branchTag": {
      "enabled": true,
      "prefix": "tc.mybranch"
    },
    "linkOnChange": {
      "enabled": true,
      "links": [
        {
          "targetId": "{env:CURRENT_STORY}",
        }
      ]
    },
    "synchronizeLinkedArtifactTitles": {
      "enabled": true,
      "linkTagPrefixes": [ "story" ]
    },
    "doNotSynchronizeTitle": {
      "enabled": true
    }
  }
  ...
```

--------------------------------

### Display SpecSync Version with Docker

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/docker-image.md

This command demonstrates how to run SpecSync using the 'latest' Docker image to display its version. It utilizes Docker's interactive mode and automatically removes the container after execution.

```text
docker run -it --rm specsolutions/specsync version
```

--------------------------------

### Upgrade SpecSync to Specific Version

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/dotnet-core-tool.md

Upgrades the SpecSync .NET tool to a specific version using the --version option with the dotnet CLI. This is also used for upgrading to preliminary versions.

```bash
dotnet tool update SpecSync.AzureDevOps --version 3.3.8
```

--------------------------------

### Running SpecSync Docker Container

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-inside-a-docker-container.md

Demonstrates how to run the SpecSync Docker image, mounting a local repository folder and passing arguments to the SpecSync command. This example pushes changes with a tag filter.

```bash
docker run -it --rm -v C:\MyProject\src\features:/local myimage push --tagFilter @foo
```

--------------------------------

### Exclude Scenarios by Feature Files

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/common-synchronization-features/excluding-scenarios-from-synchronization.md

Configures SpecSync to synchronize scenarios only from specified feature files. This example includes files from 'Folder1/' and files starting with 'alpha' in 'Folder3/', using glob patterns in the 'local/sourceFiles' configuration setting.

```text
{
  "local": {
    "sourceFiles": [
      "Folder1/",
      "Folder3/**/alpha*.feature"
    ]
  }
}
```

--------------------------------

### Configure Test Suite Synchronization

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/getting-started/getting-started-specflow.md

Shows how to configure SpecSync to automatically add synchronized test cases to a specific test suite in Azure DevOps. This involves setting the test suite name or ID in the specsync.json configuration file.

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",

  // See configuration options and samples at http://speclink.me/specsyncconfig.

  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator",
    "user": "52yny4a......................................ycsetda",
    "testSuite": {
      "name": "BDD Scenarios"
    }
  }
}
```

--------------------------------

### Initialize SpecSync Configuration

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/general-features/configuration-wizards.md

The 'init' command initializes the SpecSync configuration by creating a 'specsync.json' file based on interactive prompts. It helps set up basic configuration, verify Azure DevOps project connections, and optionally configure features like remote scope or hierarchy synchronization. It's recommended to run this from the root folder of test cases.

```text
dotnet specsync init
```

--------------------------------

### Download SpecSync v5 Preview

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/downloads.md

Provides direct download links for the v5 preview release of SpecSync. Includes platform-specific builds for Windows, Linux, and macOS, as well as a cross-platform .NET SDK version. Note that plugin support is temporarily disabled in this preview.

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.Console.5.0.0-pre20250514-1.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.5.0.0-pre20250514-1-linux-x64.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.5.0.0-pre20250514-1-osx-x64.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.5.0.0-pre20250514-1.zip
```

--------------------------------

### SpecSync Meta-data Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-with-postman.md

An example of how SpecSync meta-data is stored in the documentation of a Postman item, including the linked Test Case ID, tags, and links to other work items.

```text
This endpoint echoes the HTTP headers, request parameters and the complete  
URI requested.

## SpecSync

- tc: [1234](https://specsyncdemo.visualstudio.com/MyCalculator/_workitems/edit/1234)
- tags:
    - fast
    - important
- links:
    - story: [123](https://specsyncdemo.visualstudio.com/MyCalculator/_workitems/edit/123)
```

--------------------------------

### Download SpecSync v2.1

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/downloads.md

Provides direct download links for SpecSync version 2.1. Includes platform-specific builds for Windows and a combined OSX/Linux build.

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.Console.2.1.14.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.Mono.2.1.14.zip
```

--------------------------------

### Gherkin Feature File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/common-synchronization-features/synchronizing-test-case-hierarchies.md

An example of a Gherkin feature file demonstrating the use of tags to define hierarchy aspects like component and test category.

```gherkin
Feature: Card Payments

@component:FrontEnd
Rule: Card payment can be initiated from the UI

  @smoke
  Scenario: Card payment is started (#1)
  (...)
  
  @regression
  Scenario: Card payment is successful (#2)
  (...)

Rule: Card payment is logged

  @component:BackEnd
  @regression
  Scenario: Card payment is added to transaction log (#3)
  (...)
```

--------------------------------

### SpecSync Push Command Usage

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/push-command.md

Demonstrates the basic usage of the 'dotnet specsync push' command to synchronize local changes to Azure DevOps.

```text
dotnet specsync push
```

--------------------------------

### SpecFlow Plugin Packages for SpecSync

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/installation/setup-and-configure.md

Lists the SpecSync NuGet packages required for SpecFlow projects to support the 'Test Suite based execution with Scenario Outline wrappers' automation strategy. The package depends on the SpecFlow version.

```text
SpecSync.AzureDevOps.SpecFlow.2-3
SpecSync.AzureDevOps.SpecFlow.2-4
SpecSync.AzureDevOps.SpecFlow.3-0
SpecSync.AzureDevOps.SpecFlow.3-1
SpecSync.AzureDevOps.SpecFlow.3-3
```

--------------------------------

### Install libssl1.0.0 on Ubuntu 22.04 for SpecSync Linux Binaries

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/contact/troubleshooting.md

Installs a compatible libssl library for older SpecSync Linux binaries on Ubuntu 22.04, resolving 'No usable version of libssl was found' errors.

```text
RUN wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5_amd64.deb \
    && dpkg -i libssl1.0.0_1.0.2n-1ubuntu5_amd64.deb
```

--------------------------------

### Download SpecSync v2.0

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/downloads.md

Provides direct download links for SpecSync version 2.0. Includes platform-specific builds for Windows and a combined OSX/Linux build.

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.2.0.0.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.Mono.2.0.0.zip
```

--------------------------------

### Gherkin Feature File Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/common-synchronization-features/synchronizing-test-case-hierarchies.md

An example Gherkin feature file demonstrating 'Card Payments' with two rules: 'Card payment can be initiated from the UI' and 'Card payment is logged'. Scenarios are tagged with '@smoke' and '@regression'.

```gherkin
Feature: Card Payments

Rule: Card payment can be initiated from the UI

  @smoke
  Scenario: Card payment is started (#1)
  (...)
  
  @regression
  Scenario: Card payment is successful (#2)
  (...)

Rule: Card payment is logged

  @regression
  Scenario: Card payment is added to transaction log (#3)
  (...)
```

--------------------------------

### Install SpecSync as .NET Core Global Tool

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-inside-a-docker-container.md

Installs the SpecSync.AzureDevOps package as a global .NET Core tool within a Docker image. This is suitable for .NET Core SDK-based images. The version can be specified or left optional.

```bash
RUN dotnet tool install --global SpecSync.AzureDevOps --version 3.0.2
```

--------------------------------

### Download SpecSync v3.2

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/downloads.md

Provides direct download links for SpecSync version 3.2. Includes platform-specific builds for Windows, Linux, and macOS, along with a cross-platform .NET SDK version.

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.Console.3.2.13.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.3.2.13-linux-x64.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.3.2.13-osx-x64.zip
```

```zip
https://www.specsolutions.eu/media/specsync/SpecSync.AzureDevOps.3.2.13.zip
```

--------------------------------

### fieldUpdates Configuration Example

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization/configuration-synchronization-fieldupdates.md

This JavaScript configuration snippet demonstrates how to use the 'fieldUpdates' section to specify updates for different Test Case fields. It includes examples of simple value updates, conditional updates based on tags, and using placeholders.

```javascript
{
  "synchronization": {
    "fieldUpdates": {
      "field1": "value1",
      "field2": {
        "condition": "@tag1",
        "value": "value2",
        "removeMatchingTags": false
      },
      "field2": {
        "conditionalValue": {
          "@tag1": "value3",
          "@tag2": "value4",
          "otherwise": "value5"
        },
        "update": "onCreate"
      },
      "field3": {
        "condition": "@mytag:*",
        "value": "{1}"
      }
    }
  }
}
```

--------------------------------

### Exclude Folders from Synchronization

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/important-concepts/using-specsync-with-postman.md

Uses the 'local.sourceFiles' setting to exclude specific folders from synchronization. This example excludes the 'Legacy' folder.

```json
{
  "local": {
    "sourceFiles": [
      "not '**/Legacy'"
    ]
  }
}
```

--------------------------------

### Display SpecSync Version

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/command-line-reference/README.md

Demonstrates how to invoke the SpecSync command line tool to display its version information.

```dotnetcli
dotnet specsync version
```

--------------------------------

### SpecSync Push Command Options

Source: https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/features/push-features/pushing-scenario-changes-to-test-cases.md

Provides information on useful command-line options for the SpecSync push command, including disabling local changes, linking only, and dry-run mode.

```bash
specsync push --disableLocalChanges
specsync push --linkOnly
specsync push --dryRun
```
Tokens:
Raw