https://github.com/jojoee/gherkinfmt
GHERKIN/FEATURE formatter - zero configuration, one way to format
https://github.com/jojoee/gherkinfmt
development feature formatter gherkin linter nodejs style-guide
Last synced: 13 days ago
JSON representation
GHERKIN/FEATURE formatter - zero configuration, one way to format
- Host: GitHub
- URL: https://github.com/jojoee/gherkinfmt
- Owner: jojoee
- License: mit
- Created: 2026-01-18T15:31:53.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-19T13:18:28.000Z (5 months ago)
- Last Synced: 2026-01-19T14:54:18.560Z (5 months ago)
- Topics: development, feature, formatter, gherkin, linter, nodejs, style-guide
- Language: TypeScript
- Homepage: https://jojoee.github.io/gherkinfmt/demo/
- Size: 173 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gherkinfmt
Opinionated Gherkin formatter - zero configuration, one way to format.
[](https://badge.fury.io/js/gherkinfmt)
[](https://www.npmjs.com/package/gherkinfmt)
[](http://opensource.org/licenses/MIT)
[](https://packagephobia.com/result?p=gherkinfmt)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/jojoee/gherkinfmt/actions/workflows/continuous-integration.yml)
[](https://github.com/jojoee/gherkinfmt/actions/workflows/release.yml)
[](https://github.com/jojoee/gherkinfmt/actions/workflows/runnable.yml)
[](https://codecov.io/gh/jojoee/gherkinfmt)
## Philosophy
Like [Standard.js](https://standardjs.com/) for JavaScript - no configuration, no debates. One way to format Gherkin/Cucumber feature files.
## Installation
```bash
# npm
npm install gherkinfmt
# yarn
yarn add gherkinfmt
# pnpm
pnpm add gherkinfmt
# global install for CLI
npm install -g gherkinfmt
```
## Usage
### CLI
```bash
# Check if files are formatted (validates without modifying)
gherkinfmt --check file.feature
# Check multiple files with glob pattern
gherkinfmt --check "src/**/*.feature"
# Check all .feature files in current directory
gherkinfmt --check "*.feature"
# Check all .feature files in directory (recursive)
gherkinfmt --check src/
# Format files in-place (overwrites)
gherkinfmt --write file.feature
# Format multiple files with glob pattern
gherkinfmt --write "src/**/*.feature"
# Format all .feature files in directory (recursive)
gherkinfmt --write src/
# Show help
gherkinfmt --help
# Show version
gherkinfmt --version
```
Glob patterns support:
- `*` - matches any characters except path separator
- `**` - matches any characters including path separator (recursive)
- `?` - matches single character
- `{a,b}` - matches either pattern
Exit codes:
- `0` - All files are formatted correctly (check) or formatted successfully (write)
- `1` - Some files need formatting, errors occurred, or no mode specified
### API
```typescript
import { check, format } from 'gherkinfmt';
// Check if Gherkin string is formatted correctly
const isFormatted = check('Feature: My Feature\n');
console.log(isFormatted); // true or false
// Format Gherkin string
const formatted = format('Feature:My Feature');
console.log(formatted); // 'Feature: My Feature\n'
```
### CommonJS
```javascript
const { check, format } = require('gherkinfmt');
const formatted = format('Feature: My Feature');
```
### Browser (UMD)
```html
const formatted = gherkinfmt.format('Feature: My Feature');
```
### Docker
```bash
# Check a file
docker run --rm -v $(pwd):/data ghcr.io/jojoee/gherkinfmt --check /data/file.feature
# Check all .feature files in a directory
docker run --rm -v $(pwd):/data ghcr.io/jojoee/gherkinfmt --check /data/
# Format a file
docker run --rm -v $(pwd):/data ghcr.io/jojoee/gherkinfmt --write /data/file.feature
```
## Formatting Rules
These rules are **not configurable** - that's the point!
| Rule | Value |
|------|-------|
| Indentation | 2 spaces |
| Feature keyword | No indentation |
| Background/Scenario/Scenario Outline | 2 spaces |
| Rule keyword | 2 spaces |
| Steps (Given/When/Then/And/But/*) | 4 spaces |
| Examples | 4 spaces |
| Data tables | Aligned columns |
| Doc strings | Preserved with media type |
| Tags | One per line, before element |
| Comments | Preserved in place |
| Trailing whitespace | Removed |
| Blank lines | Single between scenarios |
| End of file | Single newline |
## API Reference
### `check(input: string): boolean`
Check if a Gherkin string is formatted correctly.
```typescript
check('Feature: My Feature\n'); // true
check('Feature:My Feature'); // false (missing space)
```
### `format(input: string): string`
Format a Gherkin string according to the opinionated rules.
```typescript
format('Feature:My Feature');
// Returns: 'Feature: My Feature\n'
```
## Gherkin Features Supported
- Feature keyword
- Background
- Scenario
- Scenario Outline with Examples
- Steps (Given, When, Then, And, But, *)
- Data tables (with column alignment)
- Doc strings (triple quotes with media type)
- Tags (@tag)
- Comments (#)
- Rule keyword (Gherkin 6+)
- Descriptions (Feature, Scenario, Rule)
- Unicode and special characters
- Escaped characters in tables
## Integration
### Pre-commit Hook
```bash
# .husky/pre-commit
npx gherkinfmt --check "features/**/*.feature"
```
### VS Code Task
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Check Gherkin",
"type": "shell",
"command": "npx gherkinfmt --check features/"
}
]
}
```
### CI/CD
```yaml
# GitHub Actions
- name: Check Gherkin formatting
run: npx gherkinfmt --check "features/**/*.feature"
```
## Development
### Commands
```bash
# Install dependencies
npm install
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Build
npm run build
# Build CLI
npm run build:cli
# Lint
npm run lint
```
```bash
# Run locally
# Check a single file
node bin/gherkinfmt.js --check resource/01-minimal.feature
# Check entire resource folder
node bin/gherkinfmt.js --check resource/
# Format a single file (writes changes)
node bin/gherkinfmt.js --write resource/all-cases.feature
# Format entire resource folder (writes changes)
node bin/gherkinfmt.js --write resource/
```
## Related
- [Gherkin Specification](https://cucumber.io/docs/gherkin/reference/)
- [Cucumber](https://cucumber.io/)
- [prettier-plugin-gherkin](https://github.com/mapado/prettier-plugin-gherkin) - Prettier plugin for Gherkin files
- [Standard.js](https://standardjs.com/) - Inspiration for zero-config philosophy