Gauge for TypeScriptの言語プラグインをforkしてメンテナンスし続けられるようにする

kits

モチベーション

TypeScriptでGaugeのテストを書きたい
Language Pluginを独自に進化させたい
公式サポートが終了してるなら自分でやったろかい

kits

gaugeの公式声明

公式はここ
https://github.com/getgauge/gauge

READMEの抜粋

Important note

Gauge's official sponsorship ended in 2021. Despite this, we strived to maintain the project with our personal resources as best as possible. However, we've reached a point where we can't ensure the same level of dedication.

The core team will only look into issues in our spare time, which means slower response times. We welcome pull requests, but please anticipate significant delays in reviewing and merging.

Moreover, please consider using Gauge only if you're prepared to adopt and support it fully on your own. With our shift to community-driven maintenance, primary responsibility will fall onto individual users and contributors.

We appreciate your understanding, contributions, and continued support.

要約すると、公式サポートは2021年で切ったからコントリビューターが本当に暇なときにメンテすることにしましたよ。だからレスポンスは遅くなるよ。勘弁してね。
もしGauge使いたかったら自分たちで解決できるならGauge使ってもいいと思うよ。

ということ。

kits

現在Gaugeがサポートしている言語は

C#
Java
JavaScript
Python
Ruby

です。そしてTypeScriptはコントリビューターの一人がgauge-tsというものを作っていて、ドキュメント的にも正式にはサポートしていないが、gauge-tsを作ったコントリビュータがgetgaugeのメンテナの一人なので、半分サポートしているみたいな感じ。

つまり、

gauge install tsのようにコミュニティが作った言語プラグインが直にインストールできるのは、以下のリポジトリを経由して取得するので、XX-install.jsonが存在しているとメタデータを読み込んでインストールしてくれます。

つまりts-install.jsonもここにあって、
コミュニティが作った言語サポートではあるものの元のコアメンテナなのでこの辺も整備されているというわけ。
もし自分が作ったプラグインをgauge install XXX でやりたかったら、gauge-repositoryに組み込まれる必要があります。

ただし、自分で作ったプラグインをZIPファイル経由でインストールすることもでき、

gauge install -f 独自プラグイン.zip みたいな感じでインストールできる。つまりは公式サポートされなくても独自にプラグインを作って自分で拡張していけるスタイルになっている。

kits

本題のgauge-tsは色々と課題はあり、

https://github.com/BugDiver/gauge-ts

BugDiverさんがgauge-tsを製作・メンテナンスをしているのだが、
最後のリリースは既に2年前でTypeScriptのバージョンも3.8.4。Gaugeの持つ基本的なコア機能自体は網羅してはいるものの、継続的にメンテナンスする、という意味では断念されている状態。

現時点で非推奨なライブラリを使っていたりしてもし今後セキュリティに関するアップデートがライブラリにあってもこれらに対応されない可能性が高く、有志のDependency UpgradeのためのPRもずっとスルーされているところをみるとBugDiverさんは恐らく暇な時間をここに充てるつもりもなさそうではある。

ほなじゃーー自分でメンテナンスしていくか〜〜〜ついでに自分で書きやすいようにしちゃうのがOSSの醍醐味だろうってワケです

kits

Fork元:
https://github.com/BugDiver/gauge-ts

リポジトリ名を変更してgauge-typescriptに。

gauge init XXでインストールするために、gauge-templateもForkする
フォーク元:
https://github.com/getgauge/template-ts

こちらもリポジトリ名を変更、gauge-template-typescriptに。

kits

ひとまずgauge-typescriptに対して以下を実施

使用しているライブラリ確認、アップグレード

TSのバージョンを3.4系 -> 5.4系にアップグレード
- 非推奨になっているメソッド、廃止されたメソッドの移行
- 型が絞れない場合はasで一旦回避
ts-jestのトランスパイル用に使われているttypescriptをやめてts-patchを使う

Requirementsとなっている各種バージョンを上方に修正

Nodeは20系以降
npmではなくpnpmを推奨に
サポートするminimumのGaugeバージョンを現行latestの1.6.4に（後述）

その他の整備、修正

eslintをjs管理ではなくjsonにしてルールの整理
prettierの追加(--write実行は一旦やらない)
fork時点でgauge-tsの実装でdeprecatedになっているメソッドの廃止
- 新規で自分がメンテナンスを覚悟する以上deprecatedを残す必要もないので削除している。
forkしたことによって影響が出そうな部分の修正を加える。
- gauge-tsとなっている部分をgauge-typescriptで表現するように部分的に置換（完全に置き換えずに影響のあるところから少しずつ移行する
ドキュメントの整備
/docの中身を内容・リンク先を変更してgithub-pagesに公開、GitHubActionsの追加

kits

forkした時点で、jestのunit testがeslintエラーを含め落ちていたテストを修正もしている。

kits

ここまでで粗方ESLintエラー、Unitテストエラー、コンパイルエラーが解消されたので動作確認を実施

ビルドスクリプトを調整し、ローカル環境にpackageしたzipファイルでinstallする

pnpm packageでパッケージング

[~/dev/gauge-typescript]+[main] $ pnpm package

> gauge-typescript@0.2.1 package /Users/tkits/dev/gauge-typescript
> sh build.sh package

> gauge-typescript@0.2.1 build /Users/tkits/dev/gauge-typescript
> pnpm lint && tsc

> gauge-typescript@0.2.1 lint /Users/tkits/dev/gauge-typescript
> eslint . --ext .ts

  adding: launcher.bat (stored 0%)
  adding: runnerRuntime.ts (deflated 22%)
  adding: launcher.js (deflated 61%)
  adding: typescript.json (deflated 70%)

その後 pnpm installPluginでパッケージングした成果物を使ってinstall

[~/dev/gauge-typescript]+[main] $ pnpm installPlugin
~中略~
Successfully installed plugin 'typescript' version 0.2.1

自分が意図したバージョンでインストールできていればOK

gauge -vでインストールされているプラグインの確認もしておく

[~/dev/gauge-typescript]+[main] $ gauge -v
Gauge version: 1.6.4
Commit Hash: a550d71

Plugins
-------
html-report (4.3.0)
screenshot (0.1.0)
typescript (0.2.1)

kits

VSCodeでGaugeをインストールしておく

kits

まだ詳細に調べ切れてはいないが、VSCodeのGaugeは言語プラグインをインストールしている場合はどうやら以下のような感じで呼び出しているっぽい

インストールされている言語プラグインの中身は以下のディレクトリとファイルになっているようだ
ディレクトリ ~/.gauge/plugins/typescript/0.2.1

launcher.bat*
launcher.js*
typescript.json

typescript.jsonは以下のようになっていて、OSなどで振り分けてrun以下のlauncher.jsを呼び出す形をとっている模様

{
    "description": "TypeScript support for gauge",
    "gaugeVersionSupport": {
        "maximum": "",
        "minimum": "1.5.6"
    },
    "id": "typescript",
    "init": {
        "darwin": [
            "./launcher.js",
            "--init"
        ],
        "linux": [
            "./launcher.js",
            "--init"
        ],
        "windows": [
            "launcher.bat",
            "--init"
        ]
    },
    "lspLangId": "typescript",
    "run": {
        "darwin": [
            "./launcher.js",
            "--start"
        ],
        "linux": [
            "./launcher.js",
            "--start"
        ],
        "windows": [
            "launcher.bat",
            "--start"
        ]
    },
    "version": "0.2.1",
    "gRPCSupport": true
}

launcher.jsは詳細は省くが、runされた時に何をしているかというと、

nodeの子プロセスを作成、
ts-nodeに諸々オプションを渡し、-eでスクリプトでgauge serverに接続するためのエントリーポイントのtsスクリプトを実行、スクリプトでインポートするパス解決のためにtsconfig-pathsも使っている
ts-nodeはGAUGE_PROJECT_ROOTという環境変数のnode_module/binから呼び出されており今回でいうとgauge-typescriptを利用するプロジェクトgauge-template-typescriptのプロジェクトにts-nodeが必要になる（元のhttps://github.com/getgauge/template-tsにもts-nodeが追加されている）

具体的にはGaugeRuntimeを呼び出しており、gauge serverに接続するようになっているだけだが、
gaugeのバージョンが1.5.3未満でVSCodeのGaugeに対してgauge-tsを使うとgauge server接続時にクラッシュし続けるエラーがあるようなのでgaugeのサポートは1.6.4に変えている。

kits

インストールがようやくできたのでgauge-template-typescriptにも手をだす。

変更の概要