GherkinにMarkdownがサポートされている

2025年11月17日

Gherkin（ガーキン）は、自然言語に近い構文でシステムの振る舞いを記述できる言語です。
主にビヘイビア駆動開発（BDD）のテストを書く際に使用され、Cucumber などのフレームワークと組み合わせて利用されます。

本記事では、Cucumber における Gherkin の特徴と、Markdown で Gherkin を書く方法について紹介します。

まずは、Gherkin の .feature ファイルで書かれた例を見てみましょう。

Feature: Staying alive
  This feature describes how to stay alive,
  not the Bee Gees song.

  Rule: Eating keeps you alive
    @important @essential
    Scenario Outline: Eating cucumbers
      Given I have <start> cucumbers
      When I eat <eat> cucumbers
      Then I should have <left> cucumbers left

      Examples:
        | start | eat | left |
        |   12  |  5  |   7  |
        |   20  |  5  |  15  |

このシナリオを動かすステップ定義は、Cucumber を使うと次のように書けます。

const assert = require('assert')
const { Given, When, Then } = require('@cucumber/cucumber')

Given('I have {int} cucumbers', function (start) {
  this.cucumbers = start
})

When('I eat {int} cucumbers', function (eat) {
  this.cucumbers -= eat
})

Then('I should have {int} cucumbers left', function (expectedLeft) {
  assert.strictEqual(this.cucumbers, expectedLeft)
})

Cucumber の Gherkin は 70 を超える自然言語をサポートしており、次のリンクから確認できます。

そのため、プログラマ以外のメンバー、例えばプロダクトオーナーや QA でも、Gherkin のシナリオを仕様として読み取れるという利点があります。

E2E テストを BDD として扱い、ユーザー目線の「フィーチャー」として表現できるほか、
受け入れテスト駆動開発（ATDD）にも利用でき、プロダクトオーナーとプログラマの合意形成に役立ちます。

仕様を Gherkin で統一して書くことで、仕様がそのままテストコードとして管理できる点も魅力です。

Markdown でも Gherkin が書ける

通常、Gherkin は .feature ファイルに記述しますが、実は Markdown でも Gherkin を書くことができます。

https://github.com/cucumber/gherkin/blob/main/MARKDOWN_WITH_GHERKIN.md

Markdown で Gherkin を書くメリットは次のとおりです。

画像・リンクなど、Markdown の装飾が利用できる
ドキュメントやナレッジツールに統合しやすい
表示が美しく読みやすい
仕様書とテスト仕様を一体として扱いやすい

以下は、先ほどの .feature ファイルを Markdown Gherkin に書き換えた例です。

# Feature: Staying alive

This feature describes how to stay alive,
not the Bee Gees song.

## Rule: Eating keeps you alive

`@important` `@essential`
### Scenario Outline: Eating cucumbers

* Given I have <start> cucumbers
* When I eat <eat> cucumbers
* Then I should have <left> cucumbers left

#### Examples

  | start | eat | left |
  | ----- | --- | ---- |
  |   12  |  5  |   7  |
  |   20  |  5  |  15  |

Markdown で書くと、Feature セクションに画像を追加したり、補足リンクを挿入したりといった拡張が簡単です。

また、日本語でも同じように記述できます。

# フィーチャー: 生き延びる

実際に「生き延びる」ための方法について説明します。
Bee Gees の曲の話ではありません。

## ルール: 食べないと生きられない

`@important` `@essential`
### シナリオアウトライン: きゅうりを食べる

* 前提 きゅうりを <start> 本持っている
* もし <eat> 本食べた
* ならば <left> 本残っているはず

#### 例

  | start | eat | left |
  | ----- | --- | ---- |
  |   12  |  5  |   7  |
  |   20  |  5  |  15  |

このように、Markdown でも読みやすく自然な形で Gherkin を記述できるため、
仕様書・設計資料としても扱いやすくなります。

終わりに

Cucumber を利用しているプロジェクトはそこまで多くないかもしれませんが、
Gherkin を Markdown で書けるというのは非常に便利な仕組みです。
仕様とテストを一体として管理したい場合には特に役立つため、ぜひ参考にしてみてください。