A .NET CLI tool for linting Gherkin feature files in BDD projects. Supports SpecFlow and other BDD frameworks with configurable rules, Git pre-commit hooks, CI/CD integration, and multi-framework support (.NET 6.0, 7.0, 8.0).
A pure C# implementation of a Gherkin linter for SpecFlow and other BDD frameworks, designed to integrate seamlessly with C# projects.
Install the GherkinLinter as a .NET tool:
dotnet tool install --global gherkin-linter
Lint your feature files:
gherkin-linter lint
Set up a Git pre-commit hook to automatically lint staged feature files:
gherkin-linter install
Install the Gherkin Linter as a global .NET tool from NuGet:
dotnet tool install --global gherkin-linter
To update to the latest version:
dotnet tool update --global gherkin-linter
To uninstall:
dotnet tool uninstall --global gherkin-linter
# Lint all feature files
gherkin-linter lint
# Lint only staged feature files
gherkin-linter lint --staged
# Lint a specific feature file
gherkin-linter lint --file path/to/feature.feature
# Use a specific configuration file
gherkin-linter lint --config path/to/config.json
# Use strict mode (returns non-zero exit code when violations are found)
gherkin-linter lint --strict
# Use quiet mode (display only essential information)
gherkin-linter lint --quiet
# Install the pre-commit hook
gherkin-linter install
This will:
The linter uses a JSON configuration file named .gherkin-linter.json in your project root:
{
"include": [
"Features/**/*.feature",
"**/*.feature"
],
"exclude": [
"bin/**/*.feature",
"obj/**/*.feature"
],
"rules": {
"scenario-names": {
"enabled": true
},
"no-empty-steps": {
"enabled": true
},
"no-duplicate-scenario-names": {
"enabled": true
},
"max-step-length": {
"enabled": true,
"config": {
"length": 100
}
},
"weak-language": {
"enabled": true
}
},
"custom_rules": []
}
| Rule | Description | Configuration |
|---|---|---|
scenario-names | Ensures all scenarios have names | None |
no-empty-steps | Ensures all steps have descriptions | None |
no-duplicate-scenario-names | Checks for duplicated scenario names | None |
max-step-length | Limits step length | length: Maximum characters (default: 100) |
weak-language | Checks for weak language patterns in steps | Customizable phrase mappings for Given/When and Then steps |
indentation | Enforces consistent indentation | type, size, enforceConsistency, allowMixed, etc. |
This rule ensures that all scenarios have a name. Unnamed scenarios make it difficult to understand the purpose of the test.
# ❌ Bad - Unnamed scenario
Scenario:
Given I am on the homepage
When I click the login button
Then I should see the login form
# ✅ Good - Named scenario
Scenario: User can navigate to login form
Given I am on the homepage
When I click the login button
Then I should see the login form
This rule checks for steps that have no description.
# ❌ Bad - Empty step
Scenario: User login
Given I am on the login page
When
Then I should be logged in
# ✅ Good - All steps have descriptions
Scenario: User login
Given I am on the login page
When I enter my credentials and click login
Then I should be logged in
This rule ensures that all scenarios have unique names within a feature file.
# ❌ Bad - Duplicate scenario names
Scenario: User login
Given I am on the login page
When I enter valid credentials
Then I should be logged in
Scenario: User login
Given I am on the login page
When I enter invalid credentials
Then I should see an error message
# ✅ Good - Unique scenario names
Scenario: User login with valid credentials
Given I am on the login page
When I enter valid credentials
Then I should be logged in
Scenario: User login with invalid credentials
Given I am on the login page
When I enter invalid credentials
Then I should see an error message
This rule limits the length of step descriptions to improve readability.
# ❌ Bad - Step is too long
Scenario: User registration
Given I am on the registration page
When I enter my first name, last name, email address, phone number, street address, city, state, zip code, country, preferred contact method, and marketing preferences
Then I should be registered
# ✅ Good - Steps are concise
Scenario: User registration
Given I am on the registration page
When I fill out the registration form with valid data
And I submit the form
Then I should be registered
This rule identifies steps that use weak or ambiguous language.
# ❌ Bad - Uses weak language
Scenario: User login
Given I am on the login page
When I enter my credentials
Then I should be able to see my dashboard
# ✅ Good - Uses specific language
Scenario: User login
Given I am on the login page
When I enter valid credentials and click login
Then the dashboard is displayed with my account information
This rule enforces consistent indentation in Gherkin files.
# ❌ Bad - Inconsistent indentation
Feature: Test Feature
Scenario: Bad indentation
Given I am not indented
When I have too much indentation
Then I have wrong indentation
# ✅ Good - Consistent indentation
Feature: Test Feature
Scenario: Good indentation
Given I am properly indented
When I have consistent spacing
Then I follow the indentation rules
## Custom Rules
You can create custom rules by implementing the `IRuleProvider` interface in a new class library project:
```csharp
using System.Collections.Generic;
using GherkinLinter.Core;
namespace YourNamespace
{
public class YourCustomRuleProvider : IRuleProvider
{
public IEnumerable<RuleViolation> ApplyRule(Feature feature, Dictionary<string, object> config)
{
var violations = new List<RuleViolation>();
// Your rule logic here
// Example: Check if feature name follows a pattern
if (!feature.Name.StartsWith("JIRA-"))
{
violations.Add(new RuleViolation
{
Message = "Feature name must start with JIRA-",
Line = feature.Line
});
}
return violations;
}
}
}
Then reference your class library and add the rule to your configuration:
{
"rules": {
"your-custom-rule": {
"enabled": true,
"config": {
"yourSetting": "value"
}
}
},
"custom_rules": [
{
"path": "path/to/your/assembly.dll",
"config": {
"additionalSetting": "value"
}
}
]
}
GherkinLinter includes MSBuild targets that can be used to integrate with your build process. The targets are automatically included when you install the NuGet package.
<!-- In your .csproj file -->
<PropertyGroup>
<!-- Enable or disable the linter -->
<GherkinLinterEnabled>true</GherkinLinterEnabled>
<!-- Skip linting in CI/CD environments -->
<GherkinLinterSkipInCI>true</GherkinLinterSkipInCI>
<!-- Skip linting in directories containing test assemblies -->
<GherkinLinterPreserveTestAssemblies>true</GherkinLinterPreserveTestAssemblies>
</PropertyGroup>
For more details, see the MSBuild Integration section in the CI/CD Integration guide.
GherkinLinter now includes features to better integrate with CI/CD environments and prevent interference with test discovery and execution:
# Skip linting in CI/CD environments
gherkin-linter lint --skip-in-ci
# Skip linting in directories containing test assemblies
gherkin-linter lint --preserve-test-assemblies
For detailed information, see the CI_CD_INTEGRATION.md guide.
The strict mode flag (--strict) makes the linter return a non-zero exit code when rule violations are found. This is particularly useful in CI/CD pipelines where you want the build to fail if there are linting errors.
# Normal mode - returns exit code 0 even with violations (for development)
gherkin-linter lint
# Strict mode - returns exit code 1 when violations are found (for CI/CD)
gherkin-linter lint --strict
The quiet mode flag (--quiet or -q) reduces the verbosity of the linter output, showing only essential information such as file paths with errors, the errors themselves, and a summary count. This is particularly useful in CI/CD pipelines or when you want to focus only on the errors without additional logging.
# Normal mode - shows detailed information about the linting process
gherkin-linter lint
# Quiet mode - shows only essential information (file paths, errors, and summary)
gherkin-linter lint --quiet
For more details about quiet mode, see QUIET_MODE.md.
The linter supports multiple .NET versions (6.0, 7.0, and 8.0), allowing you to use it with your preferred .NET runtime. The tool automatically selects the appropriate version based on what's installed on your system.
.gherkin-linter.json file is in the root of your project.For more detailed output, use the verbose flag:
gherkin-linter lint --verbose
Contributions are welcome! Here's how you can contribute:
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)Please ensure your code follows the existing style and includes appropriate tests.
MIT
FAQs
A .NET CLI tool for linting Gherkin feature files in BDD projects. Supports SpecFlow and other BDD frameworks with configurable rules, Git pre-commit hooks, CI/CD integration, and multi-framework support (.NET 6.0, 7.0, 8.0).
We found that gherkin-linter demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm now supports Trusted Publishing with OIDC, enabling secure package publishing directly from CI/CD workflows without relying on long-lived tokens.
Research
/Security News
A RubyGems malware campaign used 60 malicious packages posing as automation tools to steal credentials from social media and marketing tool users.
Security News
The CNA Scorecard ranks CVE issuers by data completeness, revealing major gaps in patch info and software identifiers across thousands of vulnerabilities.