SpecSync

https://docs.specsolutions.eu/specsync
Admin
SpecSync integrates BDD scenarios with Azure DevOps Test Cases, synchronizing them and publishing...
Tokens:37,650
Snippets:301
Trust Score:8.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Display SpecSync Version

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

Invokes SpecSync to display its currently installed version. This command can be used after successful installation to verify the tool is accessible.

```bash
dotnet specsync version

```

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

### SpecSync Configuration File Example

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

An example of a SpecSync configuration file ('specsync.json') showing basic settings for connecting to an Azure DevOps project. It includes the schema URL, remote project URL, and user authentication token.

```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 Local .NET Core Tool

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

Installs the SpecSync package as a local .NET Core tool within your SpecFlow project. This command assumes the .NET Core tool manifest has already been initialized.

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

```

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

### Initialize .NET Core Tool Manifest

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

Initializes the .NET Core tool manifest for a project, which is necessary before installing local .NET Core tools like SpecSync. This command should be run from the solution folder.

```bash
dotnet new tool-manifest

```

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

### Initialize SpecSync Configuration

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

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

```bash
dotnet specsync init

```

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

### Verify SpecSync .NET Tool Installation

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

Checks if SpecSync has been installed correctly by querying its version. Running this command after installation confirms that SpecSync is accessible and ready for use within the project. A correct version number indicates a successful installation.

```bash
dotnet specsync version
```

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

### Publish Test Results to Azure DevOps with SpecSync

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

This command utilizes SpecSync to publish the generated test results (TRX file) to Azure DevOps. It analyzes the test result file and links the outcomes to corresponding Test Cases, creating a Test Run visible in the Azure DevOps portal.

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

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

### Dockerfile for SpecSync Installation

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

This Dockerfile sets up an Ubuntu environment, installs SpecSync binaries, and configures the entry point for the SpecSync command line tool. It requires `wget` and `unzip` to be installed. The output is a Docker image ready to run SpecSync commands.

```dockerfile
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" ]
```

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

### Complete SpecSync Configuration Example

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

A comprehensive JSON configuration file for SpecSync, detailing remote and local settings, synchronization behavior, formatting options, automation conditions, state management, and linking strategies. This setup enables bidirectional synchronization between Gherkin files and Azure DevOps Test Cases.

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

  "remote": {
    "projectUrl": "https://dev.azure.com/myorg/MyProject",
    "user": "myuser@example.com",
    "password": "personal-access-token",
    "testSuite": {
      "name": "BDD Scenarios",
      "testPlanId": 42
    }
  },

  "local": {
    "featureFileSource": {
      "type": "folder",
      "folder": "features"
    },
    "tags": "@automated and not @ignore"
  },

  "synchronization": {
    "enableLocalChanges": true,
    "tagPrefixSeparators": [":", "_"],
    "linkLabelSeparator": ":",

    "format": {
      "useExpectedResult": true,
      "prefixBackgroundSteps": true,
      "syncDataTableAsText": false
    },

    "automation": {
      "enabled": true,
      "condition": "@automated"
    },

    "state": {
      "setValueOnChangeTo": "Design"
    },

    "areaPath": {
      "mode": "setOnLink",
      "value": "MyProject\Team1"
    },

    "links": [
      {
        "tagPrefix": "story",
        "relationship": "Tests",
        "targetType": "User Story"
      },
      {
        "tagPrefix": "bug",
        "relationship": "Tests"
      }
    ],

    "pull": {
      "enabled": true,
      "enableCreatingScenariosForNewTestCases": true
    }
  },

  "publishTestResults": {
    "testConfiguration": {
      "name": "Windows 10"
    },
    "runType": "Automated",
    "treatInconclusiveAs": "NotExecuted"
  }
}
```

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

### Install SpecSync as .NET Local Tool

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

Installs the latest version of SpecSync as a .NET local tool from NuGet.org. This command downloads and makes SpecSync available for the current project. If encountering NuGet source issues, consider using the `--add-source` and `--ignore-failed-sources` options.

```bash
dotnet tool install SpecSync.AzureDevOps

```

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

### Interactive Docker Container Usage with SpecSync

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

Demonstrates how to run a Docker container built with SpecSync installed and interact with it. It mounts a local features directory and shows example commands for building and synchronizing test cases.

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

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

### Verify SpecSync Installation (Bash)

Source: https://docs.specsolutions.eu/specsync/installation/native-binaries

This command verifies the SpecSync installation by displaying the currently installed version. It should be run from your project folder after setting executable permissions and requires the path to the extracted SpecSync folder.

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

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

### Execute Tests and Generate TRX File

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

This command executes SpecFlow tests using the .NET CLI and configures the logger to output test results in the TRX format, specifying a fixed log file name. The resulting file is typically found in the 'TestResults' folder.

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

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

### Verify SpecSync Installation (Extracted Package)

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-console

This command verifies the SpecSync installation when the application is downloaded as a zip package and extracted. It is executed from the command line, pointing to the tools folder within the extracted SpecSync directory.

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

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

### Verify SpecSync Installation (Windows)

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-console

This command verifies the SpecSync installation by checking the installed version. It is executed from the command line, typically using the SpecSync4AzureDevOps.cmd script created in the previous step.

```bash
SpecSync4AzureDevOps.cmd version
```

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

### Initialize SpecSync Configuration (Native Binaries)

Source: https://docs.specsolutions.eu/specsync/installation/setup-and-configure

Initializes the SpecSync configuration file using native binaries. Ensure the path to the SpecSync executable is correct and run this command from the root of your feature file set.

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

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

### Invoke SpecSync Synchronization

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-local

This command demonstrates how to execute the SpecSync synchronization process. It assumes the SpecSync package is installed and accessible via the specified path. The 'push' command typically uploads feature files.

```bash
path-to-specsync-package/tools/SpecSync4AzureDevOps.exe push
```

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

### toolSettings Configuration Example (JSON)

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-toolsettings

This JSON snippet demonstrates the available settings within the 'toolSettings' configuration block. It includes parameters such as license path, disabling statistics, output verbosity, and parent configuration overrides. Ensure the 'licensePath' points to a valid license file.

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

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

### Restore .NET Local Tools for Project

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

Restores all .NET local tools defined in the project's manifest (`dotnet-tools.json`). This command is essential for team members to set up the same tools installed by others and for CI/CD pipelines to ensure SpecSync is available during builds. It should be run from the solution or repository root directory.

```bash
dotnet tool restore
```

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

### Install SpecSync NuGet Package

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-console

This command installs the SpecSync.AzureDevOps.Console NuGet package into a .NET project. The package contains the SpecSync Console App executable. No project dependencies are added by this package.

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

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

### Get Help for SpecSync Push Command

Source: https://docs.specsolutions.eu/specsync/reference/command-line-reference

This command provides detailed help information and available options specifically for the 'push' command within SpecSync.

```bash
dotnet specsync help push
```

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

### Update SpecSync .NET Tool to Latest Version

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

This command upgrades the SpecSync .NET tool to the most recent release available. It requires the .NET SDK to be installed.

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

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

### Install SpecSync as .NET Core Global Tool (Basic)

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

A basic command to install the SpecSync.AzureDevOps .NET Core global tool. It directly specifies the version and is intended for use within a Dockerfile or similar build script.

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

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

### Initialize .NET Local Tool Manifest

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

Initializes the local .NET tool configuration for a project by creating the `dotnet-tools.json` manifest file. This step is required if no .NET local tools have been used in the project before. The manifest file should be added to source control to ensure consistent tool versions across the team.

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

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

### Initialize SpecSync Configuration for a Specific Project (CLI)

Source: https://docs.specsolutions.eu/specsync/reference/command-line-reference/init-command

This command initializes the SpecSync configuration for a specified Azure DevOps project URL. It creates a 'specsync.json' file with the provided project URL, potentially simplifying the interactive setup. The output is the 'specsync.json' file.

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

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

### Initialize SpecSync Configuration (.NET Console App)

Source: https://docs.specsolutions.eu/specsync/installation/setup-and-configure

Initializes the SpecSync configuration file for a .NET Console Application. This command requires the SpecSync executable to be available and should be executed in the feature file set's root directory.

```cmd
SpecSync4AzureDevOps.cmd init
```

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

### Install SpecSync with Official NuGet Source

Source: https://docs.specsolutions.eu/specsync/contact/troubleshooting

Installs the SpecSync .NET tool while explicitly specifying the official NuGet source to resolve 'Unable to find package' errors. This is useful when custom NuGet sources are misconfigured.

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

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

### Configure SpecSync for Test Suite Grouping

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-specflow

This JavaScript configuration snippet shows how to configure SpecSync to automatically add synchronized test cases to a specific test suite in Azure DevOps. It requires the `remote.testSuite.name` or `remote.testSuite.id` to be set in the `specsync.json` file. The `projectUrl` and `user` tokens are also necessary for authentication.

```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"
    }
  }
}
```

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

### Minimal SpecSync JSON Configuration

Source: https://docs.specsolutions.eu/specsync/features/general-features/configuration-file

A basic example of a specsync.json configuration file. This file is used by SpecSync to define synchronization tasks and settings. It requires a remote project URL and supports JSON schema for validation and auto-completion.

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

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

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

### Create SpecSync Console Script (Windows)

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-console

A Windows batch script to easily execute the SpecSync .NET Console App. It sets the SpecSync version and forwards all command-line parameters to the executable. The version number must be updated manually after a SpecSync upgrade. This script assumes the package is installed in the global NuGet packages folder.

```batch
@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 %*

```

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

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

Source: https://docs.specsolutions.eu/specsync/contact/troubleshooting

Installs a compatible SSL library version on Ubuntu 22.04 to resolve 'No usable version of libssl was found' errors when running older SpecSync Linux binaries. This is typically added to a Dockerfile.

```bash
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
```

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

### Gherkin Feature File Syntax with SpecSync Tags

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-cucumber

Demonstrates how SpecSync annotates Gherkin feature files by adding a '@tc:...' tag to scenarios and scenario outlines, linking them to specific test cases. This example shows a scenario with custom tags.

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

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

### Configure for Windows Sign-in Prompt in JSON

Source: https://docs.specsolutions.eu/specsync/features/general-features/server-authentication-options

This JSON configuration snippet indicates that no specific user or password is provided, which will trigger an interactive Windows sign-in prompt for authentication with installed Team Foundation Servers. Note that this is not supported for .NET Core or native binary installations.

```json
{
  ... 
 "remote": {
    "projectUrl": "http://mytfs:8080/tfs/DefaultCollection/MyProject"
  },
  ...
```

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

### Synchronize Scenarios using SpecSync push command

Source: https://docs.specsolutions.eu/specsync/installation/setup-and-configure

This snippet demonstrates how to perform the initial synchronization of scenarios using the SpecSync 'push' command. It supports filtering scenarios by tags and can be executed via .NET Core tool, .NET Console App, or native binaries. Ensure you are in the root folder of your feature file set before execution. The --verbose option can be added for more diagnostic information in case of errors.

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

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

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

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

### JavaScript Configuration for fieldUpdates

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-synchronization/configuration-synchronization-fieldupdates

This JavaScript object demonstrates how to configure the 'fieldUpdates' section within SpecSync's synchronization settings. It shows examples of setting direct values, conditional values based on tags, and specifying update triggers like 'onCreate'. Note that duplicate keys like 'field2' in the example are illustrative of different configuration possibilities for the same field.

```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}"
      }
    }
  }
}
```

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

### Update SpecSync .NET Tool to Specific Version

Source: https://docs.specsolutions.eu/specsync/installation/dotnet-core-tool

This command allows upgrading the SpecSync .NET tool to a particular version using the --version option. This is useful for targeting stable releases or specific feature sets. Requires the .NET SDK.

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

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

### Set Executable Permissions (Bash)

Source: https://docs.specsolutions.eu/specsync/installation/native-binaries

This command is used in a bash shell to grant execute permissions to the SpecSync4AzureDevOps binary after extracting the downloaded package. This is a necessary step for running the executable on Linux and macOS systems.

```bash
chmod +x SpecSync4AzureDevOps
```

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

### JavaScript Synchronization Configuration Example

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-synchronization

This JavaScript object demonstrates the available settings for synchronization within the project configuration. It covers options for disabling local changes, setting prefixes, enabling/disabling pull and automation features, defining state changes, configuring area and iteration paths, managing linked work items, handling attachments, and formatting synchronization output.

```javascript
{
  "synchronization": {
    "disableLocalChanges": false,
    "testCaseTagPrefix": "tc",
    "pull": {
      "enabled": true,
      "enableCreatingScenariosForNewTestCases": false
    },
    "automation": {
      "enabled": true,
      "condition": "not @manual"
    },
    "state": {
      "setValueOnChangeTo": "Design"
    },
    "areaPath": {
      "mode": "setOnLink",
      "value": "\\MyArea"
    },
    "iterationPath": {
      "mode": "setOnLink",
      "value": "\\Iteration1"
    },
    "links": [
      {
        "targetWorkItemType": "ProductBacklogItem",
        "tagPrefix": "pbi",
        "relationship": "Child"
      },
      {
        "tagPrefix": "bug"
      }
    ],
    "attachments": {
      "enabled": true,
      "tagPrefixes": [
        "wireframe",
        "specification"
      ],
      "baseFolder": "resources/files"
    },
    "format": {
      "useExpectedResult": false,
      "emptyActionValue": "N/A",
      "emptyExpectedResultValue": "N/A",
      "syncDataTableAsText": false,
      "prefixBackgroundSteps": true,
      "prefixTitle": true,
      "showParameterListStep": "whenUnusedParameters"
    }
  }
}
```

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

### Gherkin Feature File Example for `levels` Hierarchy

Source: https://docs.specsolutions.eu/specsync/features/common-synchronization-features/synchronizing-test-case-hierarchies

An example Gherkin feature file demonstrating the use of tags to define aspects for hierarchy mapping. It shows how `@component`, `@smoke`, and `@regression` tags contribute to the hierarchy structure.

```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)
  (...)

```

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

### Gherkin Feature File Example

Source: https://docs.specsolutions.eu/specsync/features/common-synchronization-features/synchronizing-test-case-hierarchies

An example of a Gherkin feature file containing 'Card Payments' scenarios with different tags like '@smoke' and '@regression'. This file serves as a basis for demonstrating how the 'custom' hierarchy configuration in SpecSync categorizes these scenarios.

```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)
  [...]
```

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

### Example: Saving .NET Reqnroll Test Results to TRX

Source: https://docs.specsolutions.eu/specsync/features/test-result-publishing-features/publishing-test-result-files

This example shows how to configure the 'dotnet test' command to save test results in the TRX format for .NET Reqnroll projects. The output file name can be specified.

```bash
dotnet test --logger "trx;logfilename=my-test-results.trx"
```

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

### Push Command with Personal Access Token (CLI)

Source: https://docs.specsolutions.eu/specsync/features/general-features/server-authentication-options

This example demonstrates how to use a Personal Access Token (PAT) directly from the command line when pushing data with SpecSync. The PAT is provided as the 'user' argument.

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

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

### Run SpecSync Docker Image - Check Version

Source: https://docs.specsolutions.eu/specsync/installation/docker-image

Displays the SpecSync version by running the official Docker image tagged 'latest'. This command pulls the image if not present and executes the 'version' command within the container. Docker's '--rm' option cleans up the container after execution, and '-it' enables interactive mode for colored output and prompts.

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

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

### Azure DevOps Pipeline for SpecSync

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

This YAML pipeline configures Azure DevOps to install SpecSync, push scenarios, build and test, and publish test results. It requires SPECSYNC_USER and SPECSYNC_PAT pipeline variables to be set.

```yaml
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  # Install SpecSync as .NET tool
  - task: DotNetCoreCLI@2
    displayName: 'Install SpecSync'
    inputs:
      command: 'custom'
      custom: 'tool'
      arguments: 'install --global SpecSync.AzureDevOps'

  # Push scenarios to Azure DevOps (without local file changes)
  - task: Bash@3
    displayName: 'Sync scenarios to Azure DevOps'
    inputs:
      targetType: 'inline'
      script: |
        dotnet specsync push --disableLocalChanges \
          --user $(SPECSYNC_USER) \
          --password $(SPECSYNC_PAT)

  # Build and run tests
  - task: DotNetCoreCLI@2
    displayName: 'Build and Test'
    inputs:
      command: 'test'
      arguments: '--logger trx --results-directory $(Build.ArtifactStagingDirectory)/TestResults'

  # Publish test results to Azure DevOps
  - task: Bash@3
    displayName: 'Publish test results to Azure DevOps'
    inputs:
      targetType: 'inline'
      script: |
        dotnet specsync publish-test-results \
          --testResultFile $(Build.ArtifactStagingDirectory)/TestResults/*.trx \
          --runName "Build $(Build.BuildNumber)" \
          --user $(SPECSYNC_USER) \
          --password $(SPECSYNC_PAT)
```

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

### Integrate SpecSync Native Linux Binaries in Dockerfile

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

This example shows a conceptual Dockerfile pattern for integrating SpecSync's native Linux binaries. It involves downloading the package and unzipping it, suitable for non-.NET based Linux images. Note: The actual download URL and unzip command would be specific to the SpecSync version and distribution.

```dockerfile
# Example: Download SpecSync native Linux binaries
# RUN curl -L <SPEC_SYNC_LINUX_BINARY_URL> -o specsync.tar.gz
# RUN tar -xzf specsync.tar.gz -C /usr/local/bin
# Ensure binary is executable and in PATH
```

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

### Configure Multiple Link Types and Options in SpecSync

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-synchronization/configuration-synchronization-links

This JavaScript example shows advanced configuration of multiple link types within SpecSync's 'synchronization.links' section. It illustrates the use of 'tagPrefix', 'targetType', 'relationship', and 'linkTemplate' for diverse linking scenarios.

```javascript
{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story",
        "targetType": "User Story",
        "relationship": "Parent"
      },
      {
        "tagPrefix": "bug"
      },
      {
        "tagPrefix": "pr",
        "relationship": "Pull Request"
      },
      {
        "tagPrefix": "url",
        "relationship": "Hyperlink"
      },
      {
        "tagPrefix": "doc",
        "relationship": "Hyperlink",
        "linkTemplate": "https://docs.specsolutions.eu/specsync/{id}"
      }
    ],
    ...
  },
  ...
}
```

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

### Run SpecSync Docker Image - Push Command

Source: https://docs.specsolutions.eu/specsync/installation/docker-image

Performs a 'push' operation using the SpecSync Docker image. This command mounts the local feature file directory (e.g., 'C:\MyProject\src\features') to the container's '/local' path, ensuring local changes are preserved. The '-v' option handles the volume mounting, and the command is executed within the container.

```bash
docker run -it --rm -v C:\MyProject\src\features:/local specsolutions/specsync push
```

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

### Configure Alternate Credentials via Command Line

Source: https://docs.specsolutions.eu/specsync/features/general-features/server-authentication-options

This command-line example demonstrates how to push data using SpecSync with alternate authentication credentials. It requires specifying the user and password directly on the command line. The password can be omitted to trigger a prompt.

```bash
path-to-specsync-package/tools/SpecSync4AzureDevOps.exe push --user myalternateusername --password myalternatepassword
```

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

### Example Gherkin Feature File with Tags

Source: https://docs.specsolutions.eu/specsync/features/common-synchronization-features/synchronizing-test-case-hierarchies

This Gherkin feature file demonstrates the use of tags to define a test hierarchy. Each scenario is tagged with '@suite:' followed by a path that SpecSync can interpret to build a hierarchical structure. For example, '@suite:Payments/FrontEnd/Smoke' indicates a path through 'Payments', 'FrontEnd', and finally 'Smoke'.

```gherkin
Feature: Card Payments

Rule: Card payment can be initiated from the UI

  @suite:Payments/FrontEnd/Smoke
  Scenario: Card payment is started (#1)
  [...]
  
  @suite:Payments/FrontEnd/Regression
  Scenario: Card payment is successful (#2)
  [...]

Rule: Card payment is logged

  @suite:Payments/BackEnd/Regression
  Scenario: Card payment is added to transaction log (#3)
  [...]
```

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

### Configure Single Link Type in SpecSync

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-synchronization/configuration-synchronization-links

This JavaScript example demonstrates how to configure a single link type within the 'synchronization.links' section of SpecSync. It specifies a 'tagPrefix' to trigger the link creation.

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

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

### Gherkin Scenario Outline for Addition

Source: https://docs.specsolutions.eu/specsync/features/push-features/synchronizing-scenario-outlines

This Gherkin syntax defines a reusable test scenario with placeholders for input values and an expected output. The 'Examples' table provides concrete data sets to execute the scenario multiple times, each row representing a distinct test iteration. This structure is ideal for testing functions with various inputs.

```gherkin
Scenario Outline: Add two numbers
    Given I have entered <a> into the calculator
    And I have entered <b> into the calculator
    When I press add
    Then the result should be <result> on the screen

Examples: 
    | description   | a  | b  | result |
    | classic       | 50 | 70 | 120    |
    | commutativity | 70 | 50 | 120    |
    | zero          | 0  | 42 | 42     |
```

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

### Filtering Scenarios by Tag (Command Line)

Source: https://docs.specsolutions.eu/specsync/important-concepts/filters-and-scopes

This command-line example shows how to apply a filter to the SpecSync push operation. It synchronizes only scenarios related to a specific user story, identified by the tag '@story:123'. This allows for targeted synchronization runs based on temporary criteria.

```bash
dotnet specsync push --filter "@story:123"
```

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

### Select Pricing Folder Files with Source File Predicate

Source: https://docs.specsolutions.eu/specsync/features/general-features/local-test-case-conditions

This example demonstrates how to select all feature files located within the 'pricing' folder using the $sourceFile predicate with the '~' (matches) operator and a glob pattern.

```specsync
$sourceFile ~ pricing/
```

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

### Configure Folder Hierarchy Synchronization (JSON)

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-hierarchies

This JSON configuration snippet demonstrates how to set up a folder-based hierarchy for synchronizing test cases. It specifies the hierarchy name, type, a condition for inclusion, and the root element with its test plan and name. This is a common setup for organizing test cases.

```json
{
  "name": "folder-hierarchy",
  "type": "folders",
  "condition": "not @ignore",
  "root": {
    "testPlan": "My plan",
    "name": "Scenarios by Folder"
  }
}
```

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

### Running Custom SpecSync Docker Image with Mounted Volume

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

Illustrates how to run a custom-built SpecSync Docker image. This example demonstrates mounting the local project's features directory and passing additional SpecSync arguments like a tag filter.

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

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

### Run SpecSync Pull in Create Only Mode

Source: https://docs.specsolutions.eu/specsync/reference/command-line-reference/pull-command

Executes the SpecSync 'pull' command in 'createOnly' mode. This synchronizes unlinked Test Cases to new scenarios but does not modify existing scenarios, useful for initial setup or avoiding unintended changes.

```bash
dotnet specsync pull --createOnly
```

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

### Reqnroll Configuration Example (JavaScript)

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-reqnroll

This JavaScript object illustrates the 'reqnroll' configuration section used for synchronizing Reqnroll projects. It shows available options for controlling how scenario outlines are automated and how wrapper methods are named and categorized. This configuration is primarily for legacy automated test case synchronization.

```javascript
{
  "reqnroll": {
    "scenarioOutlineAutomationWrappers": "iterateThroughExamples",
    "wrapperMethodPrefix": "_SpecSyncWrapper_",
    "wrapperMethodCategory": "SpecSyncWrapper"
  }
}
```

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

### Configure Domain Credentials via Command Line

Source: https://docs.specsolutions.eu/specsync/features/general-features/server-authentication-options

This command-line example illustrates pushing data with SpecSync using domain user credentials. The domain and username should be enclosed in quotes if they contain special characters, and the password can be optionally provided or prompted.

```bash
path-to-specsync-package/tools/SpecSync4AzureDevOps.exe push --user "MYDOMAIN\myuser" --password mydomainpassword
```

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

### Restore .NET Core Tools for SpecSync

Source: https://docs.specsolutions.eu/specsync/important-concepts/synchronizing-test-cases-from-build

This task restores .NET Core tools, which is a prerequisite for using SpecSync if it's installed as a .NET Core tool. It should be added before other .NET Core commands in your pipeline.

```bash
- task: DotNetCoreCLI@2
  displayName: 'dotnet tool restore'
  inputs:
    command: custom
    custom: tool
    arguments: restore
```

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

### Exclude Smoke Tests from Pricing Folder

Source: https://docs.specsolutions.eu/specsync/features/general-features/local-test-case-conditions

This example shows how to select feature files from the 'pricing' folder, excluding any files whose names start with 'smoke', using combined $sourceFile predicates with 'and not'.

```specsync
$sourceFile ~ pricing/ and not $sourceFile ~ **/smoke*.feature
```

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

### Initialize SpecSync Configuration

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

Sets up SpecSync configuration for a new project interactively. It prompts for Azure DevOps project URL, authentication method, and other basic settings, creating a specsync.json file.

```bash
# Initialize configuration in the current directory (feature file set root)
dotnet specsync init

# The init command will prompt for:
# - Azure DevOps project URL (e.g., https://specsyncdemo.visualstudio.com/MyCalculator)
# - Authentication method (PAT, basic auth, or service principal)
# - Test Suite name (optional)
# - Other basic settings

# Creates specsync.json with minimal configuration:
{
  "$schema": "http://schemas.specsolutions.eu/specsync4azuredevops-config-latest.json",
  "compatibilityVersion": 3.3,
  "remote": {
    "projectUrl": "https://specsyncdemo.visualstudio.com/MyCalculator"
  }
}
```

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

### Dockerfile for Custom SpecSync Image with License and Script

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

A Dockerfile example that customizes the official SpecSync Docker image. It copies a license file and a utility script into the image, makes the script executable, and sets up the environment for running SpecSync with custom parameters, including license file path and logging.

```dockerfile
FROM specsolutions/specsync:latest

# Copy SpecSync license file and the utility script to a /shared folder
WORKDIR /shared
COPY specsync.lic .
COPY runspecsync.sh .
RUN chmod +x ./runspecsync.sh

WORKDIR /local

ENTRYPOINT [ "/shared/runspecsync.sh" ]
```

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

### Synchronize Scenario Outlines with Parameters using Gherkin and JavaScript

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

Illustrates how to synchronize Gherkin Scenario Outlines with parameterized Azure DevOps Test Cases. The JavaScript configuration controls the formatting, such as using expected results, and enables the synchronization of scenario outline examples as parameter tables.

```gherkin
# Feature file with Scenario Outline
Feature: Calculator

  @tc:2345
  Scenario Outline: Add numbers
    Given I have entered <first> into the calculator
    And I have entered <second> into the calculator
    When I press add
    Then the result should be <result>

    Examples:
      | first | second | result |
      | 50    | 70     | 120    |
      | 30    | 40     | 70     |
      | 60    | 30     | 90     |
```

```javascript
// Configuration for parameterized Test Cases
{
  "synchronization": {
    "format": {
      "useExpectedResult": true
    }
  }
}

// After push:
// - Creates/updates Test Case #2345 with parameters: first, second, result
// - Test Case steps use parameter placeholders: @first, @second, @result
// - Parameter Values table includes all example rows
// - Test results published with iteration details for each example row
```

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

### Example TestNG Test Method with SpecSync Tags

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-with-testng

Demonstrates a TestNG test method annotated with SpecSync tags. The 'tc:[test-case-id]' tag links the method to an Azure DevOps Test Case, and other tags like 'story:[work-item-id]' can link to different work items.

```java
@Test(groups = { "MyGroup", "tc:234" })
public void onePassingTest() {
    // ...
}
```

```java
@Test(groups = { "my_tag", "tc:234", "story:123" })
public void onePassingTest() {
    // ...
}
```

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

### Backend-Specific Configuration with Parent Reference (JavaScript)

Source: https://docs.specsolutions.eu/specsync/important-concepts/how-to-define-the-local-feature-set-to-be-synchronized

Configures SpecSync for the backend feature set, referencing a parent configuration file for common settings. It also defines the local feature file source and the remote test suite. This setup is used when multiple configuration files are placed in the root directory.

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

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

### Initialize SpecSync Configuration File

Source: https://docs.specsolutions.eu/specsync/features/general-features/configuration-wizards

The 'init' command initializes the SpecSync configuration by creating a 'specsync.json' file. It prompts the user for basic settings like project URL and authorization, verifies the connection to Azure DevOps, and offers optional features such as remote scope and hierarchy synchronization.

```shell
dotnet specsync init
```

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

### Override SpecSync Configuration via Command Line (Bash)

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

These examples demonstrate how to override SpecSync configuration settings directly from the command line using the `--configOverride` option. This allows for flexible, one-time changes to settings like user, test suite, or synchronization links.

```bash
# Override user setting
dotnet specsync push --configOverride "remote/user=different.user@example.com"

# Override Test Suite
dotnet specsync push --configOverride "remote/testSuite/name=Integration Tests"

# Multiple overrides with semicolon separator
dotnet specsync push \
  --configOverride "remote/user=user@example.com;remote/testSuite/name=Sprint 12"

# Add new link configuration
dotnet specsync push \
  --configOverride "synchronization/links[]/tagPrefix=epic;synchronization/links[-1]/relationship=Parent"

# Override array element at specific index
dotnet specsync push \
  --configOverride "synchronization/links[0]/tagPrefix=story"

# Override boolean and numeric values
dotnet specsync push \
  --configOverride "synchronization/automation/enabled=true;remote/testSuite/testPlanId=42"

# Set Test Configuration from command line
dotnet specsync publish-test-results \
  --testResultFile results.trx \
  --configOverride "publishTestResults/testConfiguration/name=Linux"
```

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

### Invoke SpecSync Push Command using .NET Core CLI

Source: https://docs.specsolutions.eu/specsync/important-concepts/synchronizing-test-cases-from-build

This task invokes the SpecSync 'push' command using the .NET Core CLI. It assumes SpecSync is installed as a .NET Core tool and requires the SPECSYNC_PAT environment variable for authentication. The working directory is specified for the command execution.

```bash
- task: DotNetCoreCLI@2
  displayName: 'SpecSync push'
  inputs:
    command: custom
    custom: specsync
    arguments: 'push --disableLocalChanges --user "$(SPECSYNC_PAT)"'
    workingDirectory: src/Tests/MyProject.Specs
```

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

### Invoke SpecSync Push Command

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-cucumber

This command initiates the synchronization process from the local project to Azure DevOps. It pushes the configured feature files to be linked as test cases in the specified Azure DevOps project. Ensure you are in the project root folder when executing.

```shell
$SPECSYNC_DIR/SpecSync4AzureDevOps push
```

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

### Install SpecSync as .NET Core Global Tool in Dockerfile

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-inside-a-docker-container

Installs the SpecSync.AzureDevOps .NET Core global tool within a Docker image. It allows specifying the version via an ARG and adds the tool's directory to the PATH environment variable. This is suitable for .NET Core SDK-based images.

```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0

ARG SPECSYNC_VERSION=3.3.8
ARG LOCAL_DIR=/local

RUN dotnet tool install --global SpecSync.AzureDevOps --version ${SPECSYNC_VERSION}
ENV PATH="$PATH:/root/.dotnet/tools"

WORKDIR ${LOCAL_DIR}
```

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

### Install Certificate in Docker Container for SpecSync

Source: https://docs.specsolutions.eu/specsync/contact/troubleshooting

This process outlines the steps to install a certificate within a Docker container to resolve SSL errors when SpecSync connects to Azure DevOps Server. It involves exporting the certificate, converting it, copying it to the container's CA certificates directory, and updating the certificate store. This is necessary when SpecSync runs from a Docker container and encounters certificate validation issues.

```shell
openssl x509 -inform DER -in my-certificate.cer -out my-certificate.crt
cp my-certificate.crt /usr/local/share/ca-certificates/
update-ca-certificates
```

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

### Exclude Postman Folder from SpecSync Synchronization

Source: https://docs.specsolutions.eu/specsync/important-concepts/using-specsync-with-postman

This configuration snippet demonstrates how to exclude a specific Postman folder, named 'Legacy' in this example, from being synchronized by SpecSync. It utilizes the 'local.sourceFiles' setting with a negation pattern.

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

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

### Configure Local Feature File Source (JavaScript)

Source: https://docs.specsolutions.eu/specsync/reference/configuration/configuration-local

This JavaScript object demonstrates the configuration for a local repository, specifying the type and path of the feature file source. It also includes options for filtering features by tags, defining the paths to source feature files, and setting the default language for feature files.

```javascript
{
  "local": {
    "featureFileSource": {
      "type": "projectFile",
      "filePath": "MyProject.Specs\MyProject.Specs.csproj"
    },

    "tags": "@done and not (@ignored or @planned)",

    "sourceFiles": [
      "Folder1/",
      "Folder3/**/alpha*.feature"
    ],
    
    "defaultFeatureLanguage": "en-US"
  }
}
```

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

### Execute SpecSync Upgrade Command

Source: https://docs.specsolutions.eu/specsync/reference/command-line-reference/upgrade-command

This command initiates the SpecSync configuration upgrade process. It can be run without any arguments to use the default configuration file or with a specific configuration file path.

```shell
dotnet specsync upgrade
dotnet specsync upgrade -c my-specsync-config.json
```

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

### Display Bare SpecSync Product Version (CLI)

Source: https://docs.specsolutions.eu/specsync/reference/command-line-reference/version-command

Executes the SpecSync version command with the '--bare' option to display only the product version number, omitting license and configuration details. This provides a concise output.

```bash
dotnet specsync version --bare
```

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

### Filter Source Files with CLI Argument

Source: https://docs.specsolutions.eu/specsync/features/general-features/local-test-case-conditions

This example demonstrates how to use the '--sourceFileFilter' command-line argument in the .NET SpecSync tool to filter source files using a glob pattern.

```bash
dotnet specsync push --sourceFileFilter '**/smoke*.feature'
```

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

### Name Predicate Example

Source: https://docs.specsolutions.eu/specsync/features/general-features/local-test-case-conditions

Shows how to use the name predicate to filter test cases by their exact name. This is useful for selecting specific scenarios. The predicate uses the '$name' field and the '=' operator.

```gherkin
$name = 'Check password strength'
```

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

### Configure SpecSync Local Feature File Source

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-cucumber

This snippet shows the `specsync.json` configuration to specify the local folder containing feature files for synchronization. It sets the feature file source type to 'folder' and defines the path to the 'test/features' directory.

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

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

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

### Updating Gherkin Scenario for SpecSync Synchronization

Source: https://docs.specsolutions.eu/specsync/getting-started/getting-started-cucumber

Illustrates how to modify a Gherkin scenario's title, steps, and expected results. These changes are then synchronized back to the linked test case using SpecSync.

```gherkin
@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
```

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

### Filter Scenarios During Synchronization with SpecSync CLI

Source: https://context7.com/context7/specsolutions_eu_specsync/llms.txt

Use command-line filters with the SpecSync CLI to synchronize only specific scenarios based on tag expressions. Examples include syncing only '@smoke' scenarios or syncing '@regression' but not '@slow' scenarios.

```bash
// Command line filter: Sync only @smoke scenarios
dotnet specsync push --tagFilter @smoke
```

```bash
// Command line filter: Sync @regression but not @slow
dotnet specsync push --tagFilter "@regression and not @slow"
```
Tokens:
Raw