Package Reference - @wordpress/scripts - 《WordPress開発者リソース》日本語

インストール
セットアップ
自動block.json検出とソースコードディレクトリ
- 高度な情報
check-licenses
フォーマット
lint-js
- 高度な情報
lint-pkg-json
- 高度な情報
lint-md-docs
- 高度な情報
lint-style
- 高度な情報
packages-update
- 高度な情報
plugin-zip
- 高度な情報
start
- 失敗したテストアーティファクト
- 高度な情報
test-unit-js
- 高度な情報
test-playwright
- 失敗したテストアーティファクト
- 高度な情報
Node.jsオプションの渡し方
- テストのデバッグ
高度な使用法
- ビルドスクリプトとの連携
このパッケージへの貢献

インストール

1つのnpmモジュールをインストールするだけで済みます:

npm install @wordpress/scripts --save-dev

注意: このパッケージは、長期サポートステータスのNode.jsバージョンを必要とします（アクティブLTSまたはメンテナンスLTSリリースを確認）。古いバージョンとは互換性がありません。

セットアップ

このパッケージはコマンドラインインターフェースを提供し、wp-scriptsというバイナリを公開しているため、npx – npmパッケージランナーを使用して直接呼び出すことができます。ただし、このモジュールは、プロジェクトのpackage.jsonファイル内のscriptsセクションを使用して構成されるように設計されています。この包括的な例は、含まれているほとんどの機能を示しています。

例:

{
   "scripts": {
   "build": "wp-scripts build",
   "check-engines": "wp-scripts check-engines",
   "check-licenses": "wp-scripts check-licenses",
   "format": "wp-scripts format",
   "lint:css": "wp-scripts lint-style",
   "lint:js": "wp-scripts lint-js",
   "lint:md:docs": "wp-scripts lint-md-docs",
   "lint:pkg-json": "wp-scripts lint-pkg-json",
   "packages-update": "wp-scripts packages-update",
   "plugin-zip": "wp-scripts plugin-zip",
   "start": "wp-scripts start",
   "test:e2e": "wp-scripts test-e2e",
   "test:unit": "wp-scripts test-unit-js"
   }
}

ESNext構文を使用するための開発環境を設定するために、JavaScriptビルドセットアップチュートリアルに慣れておくのも良いアイデアかもしれません。これは、buildおよびstartスクリプトの使用方法について非常に詳細な説明を提供します。

自動block.json検出とソースコードディレクトリ

 <a name="updating-to-new-release"></a>
## 新しいリリースへの更新
既存のプロジェクトを新しいバージョンの`````@wordpress/scripts`````に更新するには、[changelog](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/CHANGELOG.md)を開き、現在のバージョンを見つけ（プロジェクトのトップレベルディレクトリで`````package.json`````を確認）、新しいバージョンの移行手順を適用します。  
ほとんどの場合、`````package.json`````で`````@wordpress/scripts`````バージョンを上げ、プロジェクトのルートフォルダで`````npm install`````を実行するだけで十分ですが、潜在的な破壊的変更については[changelog](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/CHANGELOG.md)を確認することをお勧めします。このパッケージには、プロジェクト内のWordPress依存関係を更新するプロセスを自動化することを目的とした`````packages-update`````スクリプトも含まれています。  
私たちは、`````@wordpress/scripts`````をできるだけシームレスにアップグレードできるように、破壊的変更を最小限に抑えることを約束します。  
 <a name="available-scripts"></a>
## 利用可能なスクリプト
<a name="build"></a>
### ビルド
提供された構成に従ってコードを変換し、プロダクション用に準備し、最高のパフォーマンスに最適化します。  
*このスクリプトは、単一のビルドを生成した後に終了します。インクリメンタルビルドは、開発に適しているため、[start](#start)スクリプトを参照してください。*  
プロジェクトのエントリポイントは、`````src`````ディレクトリ内の`````block.json`````ファイルにあるすべてのスクリプトフィールドをスキャンすることによって検出されます。`````block.json`````のスクリプトフィールドは、同じフォルダ内の`````block.json`````への相対パスを渡す必要があります。  
*例:*  
``````bash
{
   "editorScript": "file:index.js",
   "script": "file:script.js",
   "viewScript": "file:view.js"
}
`

フォールバックエントリポイントはsrc/index.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）で、block.jsonファイルが見つからない場合に使用されます。そのシナリオでは、生成された出力はbuild/index.jsに書き込まれます。

例:

{
   "scripts": {
   "build": "wp-scripts build",
   "build:custom": "wp-scripts build entry-one.js entry-two.js --output-path=custom",
   "build:copy-php": "wp-scripts build --webpack-copy-php",
   "build:custom-directory": "wp-scripts build --webpack-src-dir=custom-directory"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run build – プロダクション用にコードをビルドします。
npm run build:custom – 2つのエントリポイントとカスタム出力ディレクトリでプロダクション用にコードをビルドします。カスタムエントリポイントのパスはプロジェクトのルートに対して相対的です。
npm run build:copy-php – プロダクション用にコードをビルドし、srcディレクトリおよびそのサブフォルダからすべてのPHPファイルを出力ディレクトリにコピーするオプションを選択します。デフォルトでは、検出されたblock.jsonファイルのrenderおよびvariationsフィールドにリストされているPHPファイルのみがコピーされます。
npm run build:custom-directory – custom-directoryをソースコードディレクトリとして使用してプロダクション用にコードをビルドします。

このスクリプトは自動的に最適化された構成を使用しますが、時にはカスタムオプションを指定したい場合があります:

--webpack-bundle-analyzer – インタラクティブなズーム可能なツリーマップでwebpack出力ファイルのサイズを視覚化することを有効にします。
--webpack-copy-php – ソースディレクトリ（デフォルトはsrc）およびそのサブフォルダからすべてのPHPファイルを出力ディレクトリにコピーすることを有効にします。
--webpack-no-externals – スクリプトのアセット生成を無効にし、デフォルトの外部リストを省略します。
--webpack-src-dir – ソースコードディレクトリのカスタマイズを許可します。デフォルトはsrcです。
--output-path – 出力ディレクトリのカスタマイズを許可します。デフォルトはbuildです。

block.jsonのviewScriptModuleフィールドに対する実験的サポートは、


コンパイルされます。`````viewScriptModule`````フィールドは`````viewScript`````フィールドに類似していますが、モジュールをコンパイルし、WordPressでModules APIを使用して登録する必要があります。
#### 高度な情報
このスクリプトは、背後で[webpack](https://webpack.js.org/)を使用しています。パッケージのトップレベルディレクトリにwebpack構成を探し、見つかった場合はそれを使用します。見つからない場合は、`````@wordpress/scripts`````パッケージによって提供されるデフォルトの構成を使用します。[高度な使用法](#advanced-usage)セクションで詳細を学びます。  
 <a name="check-engines"></a>
### check-engines
現在の`````node`````、`````npm`````（または`````yarn`````）バージョンが指定された[セマンティックバージョン](https://semver.org/)範囲と一致するかどうかを確認します。指定されたバージョンが満たされない場合、必要なバージョンをインストールするための情報が表示され、プログラムはエラーコードで終了します。  
*例:*  
``````bash
{
   "scripts": {
   "check-engines": "wp-scripts check-engines"
   }
}
`

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run check-engines – インストールされたnodeおよびnpmのバージョンを確認します。

高度な情報

それは、推奨される構成が提供されているcheck-node-versionを背後で使用しています。デフォルトの要件は、このパッケージのインストールセクションにリストされているのと同じNode.jsおよびnpmバージョンに設定されています。check-node-version docsに記載されているように、自分の範囲を指定できます。高度な使用法セクションで詳細を学びます。

check-licenses

プロジェクトのすべての依存関係がプロジェクト自身のライセンスと互換性があることを検証します。

例:

{
   "scripts": {
   "check-licenses": "wp-scripts check-licenses --prod --gpl2 --ignore=abab"
   }
}

フラグ:

--prod（または--production）：存在する場合、dependenciesのみを検証し、devDependenciesは検証しません。
--dev（または--development）：存在する場合、devDependenciesのみを検証し、dependenciesは検証しません。
--gpl2： GPLv2ライセンス互換性に対して検証します。
--ignore=a,b,c：検証のために無視するパッケージ名のカンマ区切りセット。これは、依存関係のlicenseフィールドが不正な場合に主に使用されることを意図しています。ignoredパッケージ引数は、プロジェクトの所有者によって互換性のために手動で確認されると想定されています。

フォーマット

ファイルのコーディングスタイルガイドラインを強制するのに役立ちます（デフォルトでJavaScript、JSON、TypeScript、YAMLに対して有効）一貫した方法でソースコードをフォーマットします。

例:

{
   "scripts": {
   "format": "wp-scripts format",
   "format:src": "wp-scripts format ./src"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run format – プロジェクト全体のディレクトリ内のファイルをフォーマットします。
npm run format:src – プロジェクトのsrcサブフォルダのディレクトリ内のファイルをフォーマットします。

npm run format:srcの例のようなコマンドを実行する際には、ファイル、ディレクトリ、またはglob構文、またはそれらの組み合わせを提供できます。

デフォルトでは、build、node_modules、およびvendorフォルダ内のファイルは無視されます。無視するファイルとディレクトリのリストをカスタマイズするには、プロジェクト内の.prettierignoreファイルに追加します。

lint-js

JavaScriptおよびTypeScriptファイルのコーディングスタイルガイドラインを強制するのに役立ちます。

例:

{
   "scripts": {
   "lint:js": "wp-scripts lint-js",
   "lint:js:src": "wp-scripts lint-js ./src"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run lint:js – プロジェクト全体のディレクトリ内のJavaScriptおよびTypeScriptファイルをリントします。
npm run lint:js:src – プロジェクトのsrcサブフォルダのディレクトリ内のJavaScriptおよびTypeScriptファイルをリントします。

npm run lint:js:srcの例のようなコマンドを実行する際には、ファイル、ディレクトリ、またはglob構文、またはそれらの組み合わせを提供できます。他の例を参照。

デフォルトでは、build、node_modules、およびvendorフォルダ内のファイルは無視されます。

高度な情報

それは、eslintを使用しており、@wordpress/eslint-pluginnpmパッケージに定義された推奨ルールのセットを使用しています。デフォルトのルールは、eslint docsに記載されているように、自分のルールで上書きできます。高度な使用法セクションで詳細を学びます。

lint-pkg-json


*例:*  
``````bash
{
   "scripts": {
   "lint:pkg-json": "wp-scripts lint-pkg-json",
   "lint:pkg-json:src": "wp-scripts lint-pkg-json ./src"
   }
}
`

これは、提示されたセットアップでこれらのスクリプトを実行する方法です:

npm run lint:pkg-json – プロジェクト全体のディレクトリ内のpackage.jsonファイルをリントします。
npm run lint:pkg-json:src – プロジェクトのsrcサブフォルダのディレクトリ内のpackage.jsonファイルをリントします。

npm run lint:pkg-json:srcの例のようなコマンドを実行する際には、スキャンするための1つまたは複数のディレクトリを提供できます。他の例を参照。

デフォルトでは、build、node_modules、およびvendorフォルダ内のファイルは無視されます。

高度な情報

それは、@wordpress/npm-package-json-lint-confignpmパッケージに定義された推奨ルールのセットを使用してnpm-package-json-lintを使用しています。デフォルトのルールは、npm-package-json-lint wikiに記載されているように、自分のルールで上書きできます。高度な使用法セクションで詳細を学びます。

lint-md-docs

markdownファイルのマークアップをリントするためにmarkdownlintを使用して、標準を強制します。

例:

{
   "scripts": {
   "lint:md:docs": "wp-scripts lint-md-docs"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run lint:md:docs – プロジェクト全体のディレクトリ内のmarkdownファイルをリントします。

デフォルトでは、build、node_modules、およびvendorフォルダ内のファイルは無視されます。

高度な情報

それは、markdownlintを使用しており、.markdownlint.json構成を使用しています。この構成は、リントルールをWordPress標準に合わせるように調整されており、自分の構成で上書きできます。markdownlint-cliのコマンドラインパラメータを参照してください。

lint-style

スタイルファイルのコーディングスタイルガイドラインを強制するのに役立ちます。

例:

{
   "scripts": {
   "lint:style": "wp-scripts lint-style",
   "lint:css:src": "wp-scripts lint-style 'src/**/*.css'"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm run lint:style – プロジェクト全体のディレクトリ内のCSS、PCSS、およびSCSSファイルをリントします。
npm run lint:css:src – プロジェクトのsrcサブフォルダのディレクトリ内のCSSファイルのみをリントします。

npm run lint:css:srcの例のようなコマンドを実行する際には、ファイルグロブの周りに引用符を含めることを確認してください。これにより、シェルに関係なく、globbyの機能（**グロブスターなど）を使用できます。他の例を参照。

デフォルトでは、build、node_modules、およびvendorフォルダ内のファイルは無視されます。

高度な情報

それは、stylelintを使用しており、WordPress CSSコーディングスタンダードに従った@wordpress/stylelint-config構成を使用しています。自分のルールで上書きできます。stylelintユーザーガイドに記載されているように、高度な使用法セクションで詳細を学びます。

packages-update

プロジェクトで使用されているWordPressパッケージを最新バージョンに更新します。

例:

{
   "scripts": {
   "packages-update": "wp-scripts packages-update",
   "postpackages-update": "npm run build"
   }
}

このスクリプトは、次のカスタムオプションを提供します:

--dist-tag – npmパッケージを更新する際にカスタムdist-tagを指定できるようにします。デフォルトはlatestです。これは、@wordpress/dependency-extraction-webpack-pluginを使用する際に特に便利です。これにより、ローカルテストなどのために、指定されたWordPressメジャーバージョンで使用されているバージョンのnpm依存関係をインストールできます。例: wp-scripts packages-update --dist-tag=wp-6.0。

高度な情報

このコマンドは、package.jsonファイルをスキャンして、@wordpress/で始まる名前のプロジェクト依存関係を検出します。デフォルトでは、npm install @wordpress/package1@latest @wordpress/package2@latest ... --saveを実行してパッケージバージョンを最新のものに変更します。コマンドを実行する際に--dist-tagオプションを使用して、latestとは異なるdist-tagを選択できます。

plugin-zip

WordPressプラグインのzipファイルを作成します。

例:

{
   "scripts": {
   "plugin-zip": "wp-scripts plugin-zip"
   }
}

デフォルトでは、Plugin Handbookのベストプラクティスを使用してファイルを発見します。

高度な情報

プラグインの著者がzipファイルに含まれるファイルをカスタマイズしたい場合、npm-packlistパッケージに文書化されているように、package.jsonファイルにfilesフィールドを提供できます。例:

{
   "files": [ "dir" ]
}

これは、npmパッケージtarballを作成するためにnpm packコマンドと同じロジックを再利用します。

start

提供された構成に従ってコードを変換し、開発用に準備します。スクリプトは、コードに変更を加えると自動的に再ビルドされ、ビルドエラーがコンソールに表示されます。

単一のビルドには、プロダクションに適したbuildスクリプトを参照してください。

プロジェクトのエントリポイントは、block.jsonファイル内のすべてのスクリプトフィールドをスキャンすることによって検出されます。block.jsonのスクリプトフィールドは、同じフォルダ内のblock.jsonへの相対パスを渡す必要があります。

例:

{
   "editorScript": "file:index.js",
   "script": "file:script.js",
   "viewScript": "file:view.js"
}

例:

{
   "scripts": {
   "start": "wp-scripts start",
   "start:hot": "wp-scripts start --hot",
   "start:custom": "wp-scripts start entry-one.js entry-two.js --output-path=custom",
   "start:copy-php": "wp-scripts start --webpack-copy-php",
   "start:custom-directory": "wp-scripts start --webpack-src-dir=custom-directory"
   }
}

これは、提示されたセットアップでスクリプトを実行する方法です:

npm start – 開発用にビルドを開始します。
npm run start:hot – 「ファストリフレッシュ」で開発用にビルドを開始します。ファイルに変更を加えるとページが自動的にリロードされます。
npm run start:custom – 2つのエントリポイントとカスタム出力ディレクトリを含む開発用にビルドを開始します。カスタムエントリポイントのパスはプロジェクトのルートに対して相対的です。
npm run start:copy-php – 開発用にビルドを開始し、srcディレクトリおよびそのサブフォルダからすべてのPHPファイルを出力ディレクトリにコピーするオプションを選択します。デフォルトでは、検出されたblock.jsonファイルのrenderおよびvariationsフィールドにリストされているPHPファイルのみがコピーされます。
npm run start:custom-directory – custom-directoryをソースコードディレクトリとして使用してプロダクション用にコードをビルドします。

このスクリプトは自動的に最適化された構成を使用しますが、時にはカスタムオプションを指定したい場合があります:

--hot – 「ファストリフレッシュ」を有効にします。コードに変更を加えるとページが自動的にリロードされます。現在のところ、WordPressにSCRIPT_DEBUGフラグが有効で、Gutenbergプラグインがインストールされている必要があります。
--no-watch – ウォッチャーを開始せずに開発用にビルドを開始します。
--webpack-bundle-analyzer – インタラクティブなズーム可能なツリーマップでwebpack出力ファイルのサイズを視覚化することを有効にします。
--webpack-copy-php – ソースディレクトリ（デフォルトはsrc）およびそのサブフォルダからすべてのPHPファイルを出力ディレクトリにコピーすることを有効にします。
--webpack-devtool – ソースマップの生成方法を制御します。オプションはhttps://webpack.js.org/configuration/devtool/#devtoolを参照してください。
--webpack-no-externals – スクリプトのアセット生成を無効にし、デフォルトの外部リストを省略します。
--webpack-src-dir – ソースコードディレクトリのカスタマイズを許可します。デフォルトはsrcです。
--output-path – 出力ディレクトリのカスタマイズを許可します。デフォルトはbuildです。

block.jsonのviewScriptModuleフィールドに対する実験的サポートは、


コンパイルされます。`````viewScriptModule`````フィールドは`````viewScript`````フィールドに類似していますが、モジュールをコンパイルし、WordPressでModules APIを使用して登録する必要があります。
#### 高度な情報
このスクリプトは、背後で[webpack](https://webpack.js.org/)を使用しています。パッケージのトップレベルディレクトリにwebpack構成を探し、見つかった場合はそれを使用します。見つからない場合は、`````@wordpress/scripts`````パッケージによって提供されるデフォルトの構成を使用します。[高度な使用法](#advanced-usage)セクションで詳細を学びます。  
 <a name="test-e2e"></a>
### test-e2e
エンドツーエンド（E2E）テストランナーを起動します。テストの作成は、[Jest API](https://jestjs.io/docs/en/api)と[Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/HEAD/docs/api.md)を組み合わせて行うことができます:  
> [Jest](https://jestjs.io/)は、シンプルさに重点を置いた素晴らしいJavaScriptテストフレームワークです。
>
> [Puppeteer](https://pptr.dev/)は、[DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)を介してChromeまたはChromiumを制御するための高レベルAPIを提供するNodeライブラリです。Puppeteerはデフォルトで[ヘッドレス](https://developers.google.com/web/updates/2017/04/headless-chrome)で実行されますが、フル（非ヘッドレス）ChromeまたはChromiumで実行するように構成できます。  
*例:*  
``````bash
{
   "scripts": {
   "test:e2e": "wp-scripts test-e2e",
   "test:e2e:help": "wp-scripts test-e2e --help",
   "test:e2e:debug": "wp-scripts --inspect-brk test-e2e --puppeteer-devtools"
   }
}
`

これは、提示されたセットアップでこれらのスクリプトを実行する方法です:

npm run test:e2e – すべてのe2eテストを実行します。
npm run test:e2e:help – e2eテストランナーを構成するためのすべての利用可能なオプションを表示します。
npm run test:e2e -- --puppeteer-interactive – すべてのe2eテストをインタラクティブに実行します。
npm run test:e2e FILE_NAME -- --puppeteer-interactive – 1つのテストファイルをインタラクティブに実行します。
npm run test:e2e:watch -- --puppeteer-interactive – すべてのテストをインタラクティブに実行し、変更を監視します。
npm run test:e2e:debug – すべてのテストをインタラクティブに実行し、テストのデバッグを有効にします。

Jestは、次のいずれかの一般的な命名規則を持つテストファイルを探します:

.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）サフィックスを持つファイルがspecフォルダ内の任意の深さで見つかります。
.spec.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）サフィックスを持つファイル。

このスクリプトは、Puppeteerを開始するための最適な構成を自動的に検出しますが、時にはカスタムオプションを指定する必要があります:

プロジェクトのルートにjest-puppeteer.config.jsを追加するか、JEST_PUPPETEER_CONFIG環境変数を使用してカスタムパスを定義できます。jest-puppeteerで詳細を確認してください。

すべてのテストが現在のプロセスで直列に実行されることを強制し、–runInBand Jest CLIオプションを使用して、テスト間の競合を回避します。これは、同じWordPressインスタンスを共有することによって引き起こされます。

失敗したテストアーティファクト

テストが失敗した場合、ページのスクリーンショットとHTMLスナップショットが撮影され、プロジェクトのルートにあるartifacts/ディレクトリに保存されます。これらのスナップショットは、開発中やCI環境でテストを実行する際に失敗したテストのデバッグに役立つ場合があります。

artifacts/ディレクトリは、WP_ARTIFACTS_PATH環境変数を設定して、プロジェクトのルート内の希望するディレクトリの相対パスにカスタマイズできます。たとえば、デフォルトのディレクトリをartifacts/からmy/custom/artifactsに変更するには、WP_ARTIFACTS_PATH=my/custom/artifacts npm run test:e2eを使用できます。

高度な情報

それは、背後でJestを使用しており、すべてのCLIオプションを使用できます。./node_modules/.bin/wp-scripts test:e2e --helpまたはnpm run test:e2e:help（上記のように）を実行して、すべての利用可能なオプションを表示することもできます。高度な使用法セクションで詳細を学びます。

独自のJest構成を提供したい場合は、次のようにできます。

コマンドは--config引数を受け取ります。例: wp-scripts test-e2e --config my-jest-config.js。
パッケージのトップレベルディレクトリにjest-e2e.config.js、jest-e2e.config.json、jest.config.js、またはjest.config.jsonというファイルがあります（package.jsonと同じレベル）。
テスト構成を持つjestオブジェクトをpackage.jsonファイルに提供できます。

test-unit-js

エイリアス: test-unit-jest

ユニットテストランナーを起動します。テストの作成は、Jest APIを使用して行うことができます。

例:

{
   "scripts": {
   "test:unit": "wp-scripts test-unit-js",
   "test:unit:help": "wp-scripts test-unit-js --help",
   "test:unit:watch": "wp-scripts test-unit-js --watch",
   "test:unit:debug": "wp-scripts --inspect-brk test-unit-js --runInBand --no-cache"
   }
}

これは、提示されたセットアップでこれらのスクリプトを実行する方法です:

npm run test:unit – すべてのユニットテストを実行します。
npm run test:unit:help – ユニットテストランナーを構成するためのすべての利用可能なオプションを表示します。
npm run test:unit:watch – ウォッチモードでユニットテストをすべて実行します。
npm run test:unit:debug – デバッグモードでユニットテストをすべて実行します。

Jestは、次のいずれかの一般的な命名規則を持つテストファイルを探します:

.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）サフィックスを持つファイルがtestsフォルダ内の任意の深さで見つかります。
.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）サフィックスを持つファイルがtestフォルダ内に直接あります。
.test.js（他のサポートされている拡張子: .jsx、.ts、および.tsx）サフィックスを持つファイル。

高度な情報

それは、背後でJestを使用しており、すべてのCLIオプションを使用できます。./node_modules/.bin/wp-scripts test:unit --helpまたはnpm run test:unit:help（上記のように）を実行して、すべての利用可能なオプションを表示することもできます。デフォルトでは、@wordpress/jest-preset-defaultnpmパッケージに定義された推奨オプションのセットを使用します。Jest documentationに記載されているように、自分のオプションで上書きできます。高度な使用法セクションで詳細を学びます。

独自のJest構成を提供したい場合は、次のようにできます。

コマンドは--config引数を受け取ります。例: wp-scripts test-unit --config my-jest-config.js。
パッケージのトップレベルディレクトリにjest-unit.config.js、jest-unit.config.json、jest.config.js、またはjest.config.jsonというファイルがあります（package.jsonと同じレベル）。
テスト構成を持つjestオブジェクトをpackage.jsonファイルに提供できます。

test-playwright

Playwrightエンドツーエンド（E2E）テストランナーを起動します。Puppeteerと同様に、ヘッドレスブラウザを制御するための高レベルAPIを提供します。

テストの作成方法を学ぶには、Getting Started guideを参照してください。

例:

{
   "scripts": {
   "test:playwright": "wp-scripts test-playwright",
   "test:playwright:help": "wp-scripts test-playwright --help",
   "test:playwright:debug": "wp-scripts test-playwright --debug"
   }
}

これは、提示されたセットアップでこれらのスクリプトを実行する方法です:

npm run test:playwright – すべてのテストを実行します。
npm run test:playwright:help – テストランナーを構成するためのすべての利用可能なオプションを表示します。
npm run test:playwright:debug – Playwrightインスペクターでインタラクティブにすべてのテストを実行します。
npm run test:playwright FILE_NAME – 特定のテストファイルを実行します。
npm run test:playwright -- --watch – ウォッチモードと強化されたデバッグでインタラクティブにすべてのテストを実行します。

デフォルトでは、Playwrightはプロジェクトのルートレベルの/specsフォルダ内で.testまたは.specサフィックスを持つJavaScriptまたはTypeScriptファイルを探します。たとえば、/specs/login-screen.wrong-credentials.spec.ts。

このスクリプトは、Playwrightを開始するための最適な構成を自動的に検出しますが、時にはカスタムオプションを指定する必要があります。

そのためには、パッケージのトップレベルディレクトリにplaywright.config.tsまたはplaywright.config.jsというファイルを追加できます（package.jsonと同じレベル）。

失敗したテストアーティファクト

テストが失敗した場合、ページのスナップショットが撮影され、プロジェクトのルートにあるartifacts/ディレクトリに保存されます。これらのスナップショットは、開発中やCI環境でテストを実行する際に失敗したテストのデバッグに役立つ場合があります。

高度な情報

すべてのPlaywrightのCLIオプションを使用できます。./node_modules/.bin/wp-scripts test-playwright --helpまたはnpm run test:playwright:help（上記のように）を実行して、すべての利用可能なオプションを表示することもできます。高度な使用法セクションで詳細を学びます。

Node.jsオプションの渡し方

wp-scriptsは、すべてのNode.js CLIオプションの配列をサポートしています。これらは、wp-scriptsコマンドの後、スクリプト名の前に渡すことができます。

wp-scripts [NODE_OPTIONS] script

テストのデバッグ

Node.jsオプションを渡す一般的なユースケースの1つは、テストのデバッグです。

テストは、Chrome DevTools Protocolをサポートする任意のインスペクタークライアントによってデバッグできます。

お気に入りのサポートされているブラウザやIDEでNode.jsをデバッグするための手順に従ってください。手順でnode --inspect script.jsまたはnode --inspect-brk script.jsを使用するように指示された場合は、wp-scripts --inspect scriptまたはwp-scripts --inspect-brk scriptを代わりに使用してください。

以下は、Google ChromeとVisual Studio Codeを例にしています。

Google Chromeでのデバッグ

任意のテストに debugger; ステートメントを配置し、wp-scripts --inspect-brk test-unit-js --runInBand --no-cache (または上記の npm run test:unit:debug) を実行します。

次に、Google Chromeで about:inspect を開き、プロセスの inspect を選択します。

スクリプトの最初の行にブレークポイントが設定されます（これは、開発者ツールを開く時間を与え、Jestが実行される前にそれを行うためです）。開発者ツールの右上パネルにある再開ボタンをクリックして実行を続けます。 Jestがデバッガーステートメントを含むテストを実行すると、実行が一時停止し、現在のスコープとコールスタックを調べることができます。

Visual Studio Codeでのデバッグ

npmスクリプトのデバッグは、バージョン 1.23 以降のVisual Studio Codeで標準でサポートされており、Jestユニットテストのデバッグに使用できます。

Visual Studio Codeでテストを実行するには、wp-scripts --inspect-brk test-unit-js --runInBand --no-cache が test:unit:debug として package.json ファイルに保存されていることを確認してください。

デバッグ中は、エディタの行番号の左側のマージンをクリックしてテストにブレークポイントを設定します。

次に、エクスプローラーでnpmスクリプトを開くか、コマンドパレットで Explorer: Focus on NPM Scripts View を実行してnpmスクリプトを表示します。テストを開始するには、test:unit:debug の隣にあるデバッグアイコンをクリックします。

テストが実行され始め、選択した行で実行が一時停止するので、エディタ内で現在のスコープとコールスタックを検査できます。

Visual Studio Codeデバッガーの使用に関する詳細は、Visual Studio Codeでのデバッグを参照してください。

e2eテストのデバッグ

e2eテストはノードコンテキスト および (通常はヘッドレス) ブラウザコンテキストで実行されるため、すべてのコード行にインスペクタークライアント内でブレークポイントを設定することはできません—インスペクタークライアントではノードコンテキストのみがデバッグされます。

ノードコンテキストで実行されるコードには、page.evaluate 関数内のコードを除くすべてのテストファイルが含まれます。 page.evaluate 関数とアプリの残りのコードはブラウザコンテキスト内で実行されます。

テストコード (ノードコンテキスト) は、上記の手順を使用して通常通りデバッグできます。

ブラウザコンテキストもデバッグするには、wp-scripts --inspect-brk test-e2e --puppeteer-devtools を実行します。 --puppeteer-devtools オプション (または PUPPETEER_DEVTOOLS="true" 環境変数を PUPPETEER_HEADLESS="false" と一緒に使用する場合) はヘッドレスモードを無効にし、開発者ツールがすでに開いている状態でブラウザを起動します。その後、これらの開発者ツールを使用してブラウザコンテキスト内にブレークポイントを設定できます。

e2eデバッグのヒントについては、Puppeteerデバッグドキュメントをチェックしてください。

高度な使用法

一般的に、このパッケージは推奨される設定ファイルのセットと共に使用する必要があります。提供されるすべての設定ファイルをオーバーライドすることは可能ですが、そうする必要がある場合は、あなたのユースケースが予想以上に複雑であることを意味します。その場合、全体の抽象化レイヤーを使用せず、使用するツールに対して完全な制御を持ってプロジェクトを設定する方が良いでしょう。

ビルドスクリプトとの連携

build と start コマンドは、背後で webpack を使用します。 webpackは、コードを別のものに変換するのに役立つツールです。例えば、ESNextで書かれたコードを受け取り、プロダクション用に最適化されたES5互換コードを出力することができます。

デフォルトのwebpack設定

@wordpress/scripts は、WordPressエディタによってベースとして使用されるデフォルトのwebpack設定をバンドルします。これがデフォルトです:

エントリ: プロジェクトのエントリポイントは、block.json ファイル内のすべてのスクリプトフィールドをスキャンすることで検出されます。フォールバックエントリポイントは src/index.js です (他のサポートされている拡張子: .jsx, .ts, および .tsx) block.json ファイルが見つからない場合。
出力: build/[name].js、例えば: build/index.js、または build/my-block/index.js。
ローダー:
- babel-loader は、Babelとwebpackを使用してJavaScriptおよびTypeScriptファイルをトランスパイルすることを可能にします。
- @svgr/webpack と url-loader は、JavaScriptコード内でSVGファイルを処理することを可能にします。
- css-loader は、postcss-loader と sass-loader と連携して、JavaScriptファイル内で参照されるCSS、SASS、またはSCSSファイルをwebpackが処理できるようにします。
プラグイン (他にも):
- CopyWebpackPlugin は、src ディレクトリ内で発見されたすべての block.json ファイルをビルドディレクトリにコピーします。
- MiniCssExtractPlugin は、CSSを別々のファイルに抽出します。 CSSを含むJavaScriptエントリポイントごとにCSSファイルを作成します。
- @wordpress/dependency-extraction-webpack-plugin は、デフォルト設定で使用され、WordPressが提供するスクリプトがビルドバンドルに含まれないようにします。

CSSの使用

例:

// index.scss
$body-color: red;
.wp-block-my-block {
   color: $body-color;
}

/* style.css */
.wp-block-my-block {
   background-color: black;
}

// index.js
import './index.pcss';
import './index.scss';
import './style.css';

デフォルトコマンド wp-scripts build (start にも適用) を使用してビルドを実行すると、build フォルダに生成されたJavaScriptファイルに加えて、さらに2つのファイルが表示されるはずです:

1. index.css – すべてのインポートされたCSSファイルが、エントリポイントにちなんで名付けられた1つのチャンクにバンドルされ、デフォルトは index.js であり、したがって作成されたファイルは index.css になります。これはエディタでのみ使用されるスタイル用です。
2. style-index.css – インポートされた style.css ファイル (PCSS、SASS、SCSS拡張子に適用) が、フロントエンドとエディタの両方で使用されることを目的とした1つの style-index.css ファイルにバンドルされます。

スクリプトのドキュメントに記載されているように、複数のエントリポイントを持つこともできます:

wp-scripts start entry-one.js entry-two.js --output-path=custom

そうする場合、生成されるCSSファイルはエントリポイントの名前に従います: entry-one.css と entry-two.css。

エントリポイント名に style キーワードを使用しないでください。これによりビルドプロセスが壊れる可能性があります。

CSSモジュールをバンドルするには、拡張子の前に .module を付けることができます。例: style.module.scss。そうでない場合、これらのファイルは他のすべての style.scss と同様に処理されます。それらは style-index.css にも抽出されます。

フォントと画像の使用

フォント (woff, woff2, eot, ttf および otf) と画像 (bmp, png, jpg, jpeg, gif および wepb) ファイルを、前のセクションで説明したようにwebpackによって制御されるCSSから参照することが可能です。

例:

/* style.css */
@font-face {
   font-family: Gilbert;
   src: url( ../assets/gilbert-color.otf );
}
.wp-block-my-block {
   background-color: url( ../assets/block-background.png );
   font-family: Gilbert;
}

SVGの使用

例:

import starUrl, { ReactComponent as Star } from './star.svg';
const App = () => (
   <div>
   <img src={ starUrl } alt="star" />
   <Star />
   </div>
);

独自のwebpack設定を提供する

独自のwebpack設定を提供したい場合は、そうすることができます。 build と start コマンドは、次の場合に提供されたファイルを使用します:

コマンドが --config 引数を受け取る場合。例: wp-scripts build --config my-own-webpack-config.js。
プロジェクトのトップレベルディレクトリ (package.json と同じレベル) に webpack.config.js または webpack.config.babel.js というファイルがある場合。

webpack設定の拡張

提供されたwebpack設定を拡張するか、提供されたwebpack設定内のサブセクションを置き換えるには、独自の webpack.config.js ファイルを提供し、提供された webpack.config.js ファイルを require し、spread 演算子を使用して提供された設定のすべてまたは一部をインポートします。

以下の例では、webpack.config.js ファイルがルートフォルダに追加され、提供されたwebpack設定を拡張して、モジュールのソースを解析し、tomlを使用してJavaScriptオブジェクトに変換するカスタムロジックを含めます。特定のローダーなしでtomlや他の非JSONファイルをJSONとしてインポートすることが役立つ場合があります:

const toml = require( 'toml' );
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
module.exports = {
   ...defaultConfig,
   module: {
   ...defaultConfig.module,
   rules: [
   ...defaultConfig.module.rules,
   {
   test: /.toml/,
   type: 'json',
   parser: {
   parse: toml.parse,
   },
   },
   ],
   },
};

このアプローチを採用する場合は、次のことに注意してください:

wp-scripts コマンド (start と build) を引き続き使用する必要があります。 webpack を直接使用しないでください。
このパッケージの将来のバージョンでは、バンドルするwebpackおよびBabelプラグイン、デフォルト設定などが変更される可能性があります。それらの変更が必要な場合は、パッケージのCHANGELOGに登録されるので、アップグレードする前に必ず読んでください。

このパッケージへの貢献

これはグーテンベルクプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。

このパッケージやグーテンベルク全体への貢献について詳しく知りたい場合は、プロジェクトの主な貢献者ガイドをお読みください。