H1タグの複数使用とページタイトルへの適用可否について軽く調べた

前回のジャンル::調査の記事(2025/05/14執筆)から一年半ほど、久々の調査記事だ。今回は前々から気になっていたが調べてこなかったことについて調べたので、そのことを書いてゆく。

一個前の記事にもあるとおり、ここ最近CMSの開発を続けていて、どうしても記事本文の見出しレベルを上げて使えるHタグを一つでも増やしたい思いが募っていたので、これの実現性について調べることにした。

先に断っておくと私はWebアクセシビリティの専門家ではないし、単なる素人だ。よってこの記事に書いてあることはすべて素人判断である。

考え始めたきっかけ

現在このサイトでは記事本文中に書いた見出し構文(#)はH3から始まることになっており、H2から始めたい思いがあった。これは単に使える見出しの深さが増えるからだ。HタグはH6までしかないので、使えるHタグの数が増えるのは嬉しいことだった。

Hタグが足りない問題はLyndbaumより前、adiaryよりもっと前、WordPressを使っていたころから、ずっと思っていた。これは私がやたら長文を書いてしまったり文章構成がへたくそな部分も大いにあると思うが、深いHタグが欲しくなるケースが多々あったのだ。今でもそうだ。

かつては仕事で使っていたDocBaseに対して使えるHeadingの階層を増やしてほしいと要望を出したこともあるくらい、それほどまでに私は見出しに拘っている。

私は見出しに対して非常に執着心があり、5年前にはRedmineの見出し目次を追従させるuser.jsを書いてたほどで、その魂は見出し追従機能を持つLyndbaumの標準テーマにも引き継がれている。

それゆえに使える見出しの階層を増やすことができないかというのは長年の悩みだった。

記事タイトルをH1にすることで、記事内のHを一段階上げることができる対比図

もし左の構造を右の構造に転換できればH3始まりをH2に始まりにできるわけだ。

ただ、この案には一つ引っかかる点があった。記事ページだけを見れば、H1は記事タイトルの一つだけになるので何の問題もない。しかしこのサイトは一覧ページに記事全文が並ぶ古典的なレイアウトなので、一覧ページでは記事の数だけH1が並ぶことになる。私の理解ではH1は1ページに一つ、ページタイトルに対して使うものであり、これを愚直にやってしまうとHTMLセマンティクスを壊してしまう懸念があった。

しかし、私は同時に「サイトの中にH1を複数配置することは問題ない」という相反する情報も持っていた。いつ見聞した情報かは全く記憶にないが、頭の中にあった情報だ。

そこでまず、この情報の真偽を調べることにした。

H1タグは何であり、どう使うことができるのか?

こういう時に頼りになるのはMDNだと思って私はすぐに<h1>–<h6> セクション見出し要素 - HTML | MDNを開いてみたが、核心的な情報はなかった。

<h1>~<h6>はHTMLの要素で、セクションの見出しを6段階で表します。<h1>が最上位で、<h6>が最下位です。

MDNに書かれていたH1、もといHタグの説明は大まかにはこの一行だった。あとは精々次のような注意書きがあっただけである。

1つのページに複数の<h1>要素を使用しない

1つのページに複数の<h1>要素を使用することはHTML標準では認められていますが(入れ子でない限り)、これはよい習慣とはみなされません。

つまりH1とは見出しである。1つのページに複数の<h1>要素を使用することは、HTML標準では認められていても、よい習慣ではないと書いてあるだけだ。何が良くないのかは全く書かれていない。

ひとまず私は1つのページにH1を複数配置することは問題になる可能性があるということを覚えた。

世間がHタグをどのように使っているか調べてみた

MDNに具体的な説明がないので困った私は適当に思いついたサイトをピックアップして、Hタグがどのように使われているかを簡単に調べてみることにした。すると面白い発見があった。

20個のサイトでHタグの使用状況を調べた

調べたサイトの数が20個なのは、これ以上良いサイトがぱっと出てこなかったからである。部分的な項目についてはこの表にないサイトも見ている。

サイトのリンク先には不適切なものも含まれるため注意。リンクは後から足したため、確認したページと異なる可能性がある。参考程度の情報。また1サイト数分で見ている*1ため内容には誤りがある可能性がある。

サイト サイトタイトル 一覧の記事タイトル 一覧に記事全文が出る 記事ページタイトル 記事の開始H 備考
Daring Fireball Hなし H1 〇 H1 H2 H1がたくさんある。Markdownの始祖だが...
るるせなーれ Hなし H1 〇 H1 H2 WordPress theme EASEL
はてなブログ H1 H1 〇 H1 H1 任意のブログを何個かピックアップし、自分のアカウントでも確認
Serene Bach v4 H1 H2 〇 H2 H1 セルフホストして初期状態で確認
caniuse Hなし H3 〇 H3 H4 H2はフッターの一要素にある
Reddit Hなし Hなし × H1 H1 記事ページにはH1を複数作れて、実際に作られている
神戸新聞 H1 Hなし × H1 - 記事ページにはH1が二つある。記事本文中に見出しがない
MDN Hなし Hなし × H1 H2
ci-en Hなし H2 × H1 H2 ページによってはH2の中にH1があるので余り参考にならない(恐らく実装的にページコンポーネントをH2があるコンポーネントの中にincludeしている
Yahoo!ニュース H1 Hなし × H1 H2 記事ページにはH1が二つある
NovelAI Journal Hなし H2 × H1 H3 不自然にH3になっていることから、恐らく原文は見出しを##で書いていると思われる
Storybook Blog Hなし H2 × H1 H2
ICS MEDIA H1 H2 × H2 H3 一覧ページにはサイトタイトルと「一覧」中タイトルの二箇所にある
hacktk.net Hなし Hなし × H1 H2
ジブンノート Hなし Hなし × H1 H2 中タイトル方式
さくマガ Hなし H2 × H1 H2
uga.dev H1 Hなし × H1 H2 記事ページにはH1でサイトタイトルが出ない
p-hone.info Hなし Hなし × H1 H2
PukiWiki H1 一覧機能がない 一覧機能がない Hなし H2
SSP ヘルプ Hなし 一覧機能がない 一覧機能がない H1 H2

*1 : AIとかなしの完全目検です。

20個のサイトで確認した、使用割合の結果

調べた結果、次のことが分かった。

指標 実数 割合
総数 20 100.00%
記事本文の最初のHタグがH2 13 65.00%
記事ページで記事タイトルがH1 16 80.00%
一覧に記事全文 5 25.00%
サイトタイトルにHタグがない 13 65.00%
一覧の記事タイトルがH1 3 15.00%

つまり過半数のサイトでサイトタイトルにH1が使われていないし、過半数のサイトで記事ページで記事タイトルがH1だし、過半数のサイトは記事の最初に出てくるHタグがH2なのだ。

これは記事ページに限って言えば、私がやろうとしている構成は多数派に属するということを意味する。残る論点は、全文が並ぶ一覧ページでH1が複数になることだけだ。

その一覧ページについては、一覧の記事タイトルをH1にしているサイトは2つしかなかった。ただし、一覧に記事全文を出しているサイトが20サイト中5サイトしかないので、そもそもの母数が小さい。

この少ない母数に入るサイトの中でDaring Fireballとるるせなーれは、私にとってはかなり理想形だった。何故なら、サイトタイトルがHなし、一覧と記事ページの記事タイトルがH1で、本文中に出現する最初のHタグはH2だったからだ。これがあるべき姿なのかどうかは議論の余地がありそうだが、運命みたいなものは感じた。だって私がやろうとしてるのはサイトのH階層を浅くして、MarkdownパーサーのH階層を一段上げることだからだ。

もう一つがはてなブログだ。個人的にはSEOに強い印象がなく、かつて使っていた限りでは、ろくにインデックスされた記憶もない。しかし、はてなブログはこの形式でも一応インデックス自体はされているので、つまり検索エンジンのクローラーが読んでくれる可能性があるということだ。あとは評価がどうなるかという部分にはなってくる。

サイトタイトルについていえばGitHubもBulmaやMaterial UIの公式サイトもいわゆるヒーローバナーのタイトルにH1は入っていない。つまりここは削れる公算が大きい。そもそも<title>に書いてあることと同じ文字列にH1が必要かどうかは一つ疑問でもある。

H1タグが1ページに複数あるサイトは検索エンジンからどう評価されるのか?

Google公式SEOスターターガイド | Google検索セントラルによると、Googleはセマンティクスをそもそも評価していないらしい。それも見出しに焦点を当てて説明がされているほどにだ。

見出しの数や順序
見出しを意味的な順番にすることは、スクリーンリーダーにとっては素晴らしいことですが、Google検索にとっては順番どおりに使われていなくても問題ありません。ウェブは一般に正しくないHTMLで書かれています。そのため、Google検索がHTML規格に潜むセマンティックスの意味に依存することはめったにありません。

また、ページごとに魔法の見出し数や理想的な見出し数といったものが存在することもありません。ただ、リンクの数が多すぎると感じる場合、実際にそうである可能性が高いと言えます。

つまり見出しの意味はGoogleにとって無価値な可能性があり、ページにH1が複数あっても、SEO上はほとんど問題にならないかもしれない。

アクセシビリティ上はどうか?

Googleの説明にもある通り、見出しの構造が一番有用になってくるのはスクリーンリーダーだと考えている。なので本来ここが一番大事な論点なのだが、正直なところ私には確かなことが言えない。私はスクリーンリーダーのユーザーではないので、自分で良し悪しを判断できない。そして調べても確定的な情報を得ることはできなかった。

私の認識ではHタグはスクリーンリーダー向け以外にはほとんど役に立っておらず、目が見えていれば、かなりどうでもいいものだと思う。何故なら文字を大きくする目的だけでHタグが使われるのはよくあることだからだ。つまり誰も気にしてなんかいない。

何よりモダンなブログのように記事一覧がタイトルとようやくで並んでない古典的レイアウトのサイトで考えることではないだろうし、ひとまずH1の多用がHTMLとしてVALIDなのであれば、それはもう必要以上に気にしても仕方がないような気がした。

出来る範囲で配慮したほうがいいとは思うが、WCAGを守ることは義務ではない。インターネットは自由だ。映画館やホール、スタジアムの座席がすべて車いす対応でないように、K2やエベレスト、富士山に車いすスロープがないように、アクセシビリティは必ず何もかもすべてが満たす義務はない。大抵の家には階段しかなく、エレベーターはない。

しかしソフトウェアの開発者であれば守るべきかもしれない。しかしはてなブログは守っていない。どこまで拘るか、これは決めの問題でしかない。ならば、私はH2を本文で使いたい、そう思えた。

WCAGは何といっているか?

軽く見た範囲では何も言ってなさそうだった。全部は見てない。

少なくともH42: 見出しを特定するために、h1 要素~ h6 要素を使用するやF43: 達成基準 1.3.1 の失敗例 - コンテンツにおける関係を表さない方法で、構造的なマークアップを使用しているには1ページに複数のH1を書くなとはどこにもない。階層を守れ、飛ばすなくらいしか書かれていない。

LLMは何と言っているか?

Claude Opus 5.5によると記事一覧の記事タイトルがH1であることはスクリーンリーダー利用者によって記事タイトルだけを飛ばし読みする場合に有益な場合があると言っていた。本当かどうかは知らない。何故なら私はスクリーンリーダー使用者ではないからだ。

なら自分がスクリーンリーダーを使ってみればいいのでは?

もちろん、私もスクリーンリーダーを導入すれば使うこと自体はできる。ただその使い方が視覚障害者と同じであるかどうかは、私にはわからない。これは聾者とコミュニケーションをとるときに筆談すれば伝わりやすいという誤謬と同じだ。

筆談ができる聾者は少なくないが、得意であるとは限らない。書き言葉は音声言語を土台にしており、言葉は本来、耳から聞いた情報をもとに身につくものだからだ。つまり筆談は、もともと聴覚を持っている人を前提とした手段であり、先天的な聾者には必ずしも当てはまらないとされている。この点は「特集/聴覚障害者のコミュニケーション ろう者コミュニケーションの諸問題」などに詳しい。

同様に、晴眼者がスクリーンリーダーを使ったところで、視覚障害者と同等の経験が得られるかといえば、私は疑問に思う。理解できたとしても、それはあくまで晴眼者の範疇での理解にとどまるだろう。

はてなブログを利用している視覚障害者は存在するのか?

手っ取り早い方法としてH1まみれのはてなブログを利用している視覚障害者がもし存在すれば、それはつまりスクリーンリーダー的に問題がない可能性があるというので調べてみた。すると利用者を確認することができた。

neputa noteというブログははてなブログで作られており、ロービジョンの方が運営されているとある。DOM構造もサイトタイトルがH1、一覧の記事タイトルがH1、記事本文の最小見出しはH2だ。

もちろん、このサイトの存在を以って直ちに問題ないと判断することはできない。何故なら失礼な話、このサイトの運営者がロービジョンであることを確かめる術が私にはないからだ。とはいえ、妙な広告なども見られないので書いてあることは正しいようにも見える。

結論

サイトタイトルはHなし、記事タイトルはH1、本文中の最小見出しはH2にすることで私の理想が叶うのではないかと思った。恐らくSEOには大きく影響せず、ある程度のマシンリーダブル性も担保できるのではないかと考えた。

もちろん確たる根拠も何もない。あくまで今回の簡易な調査で分かったことでしかないし、アクセシビリティの専門家は異を唱えるかもしれない。しかし、これは結局のところ決めの問題だ。Lyndbaumの開発者たる私がそう決めたら終わる話なのだ。

最終的な構成案の対比図

というわけで次回のバージョンでMarkdownパーサーとテンプレートに手を入れ、サイトタイトルをHなし、記事タイトルをH1、本文の最小見出しをH2にしようと思うのであった。

2026-11-18追記

昨日、17日から試験的にこのサイトで上記形式を試している。Nu Html CheckerやPageSpeed Insightsでは特に見出しに関する違反が見られなかったので恐らく問題なさそうだ。但し本記事は引用内容の関係で見出しレベルが壊れている箇所があるので、そこの問題は出ている。これは引用なのでいかんともしがたい部分だ。

Ctrl+F5は消えたのか?

Ctrl+F5でスーパーリロードの操作をしていたら「スーパーリロードはShift+F5だろJK(常識的に考えて)」みたいな指摘を受けたので、Ctrl+F5でスーパーリロードが機能するかどうかを調べてみた。

結論を書くと実際に確認したところ、主要ブラウザでは今でも機能した。

各ブラウザの挙動

Microsoft Edge

機能する。

Microsoft公式によるとShift+F5となっているが、バージョン136.0.3240.64ではCtrl+F5でも機能していた。もしかしたら互換機能として残っているのかもしれない。

Google Chrome

機能する。

公式ヘルプによるとCtrl+F5は別の機能に割り当てられていた。

しかし、バージョン136.0.7103.93ではCtrl+F5でも機能していた。

Firefox

機能する。

公式ヘルプによると機能すると書かれている。

バージョン138.0.3で機能することも確認した。参考までにFirefoxではShift+F5は開発者メニュー的なものが開いた。

Opera

機能する。

公式ヘルプには記載がないが、バージョン134.0.6998.205で機能することを確認した。

設定画面上には存在していた。

まとめ

Ctrl+F5は依然としてスーパーリロードとして機能するようだ。但しEdgeやChromeのヘルプを見る感じCtrl+F5の扱いが表記されておらず、Shift+F5に機能を移したいような意図も感じられたため、そのうち使えなくなる可能性もあるかもしれないなと感じた。

スマホサイトでのキーボード挙動まとめ

スマホでWebを見てるときにキーボードがUIにかぶって操作しづらくなることがあるので、いくつかのサイトでどうなっているか調べてみた。

去年の9月にAndroid Edgeで調べた内容なので、今とは事情が異なるケースもある。Android Chromeでは起きなかったケースもあったので、Edge特有の挙動と思われる。

Twitter

ログイン画面

キーボードが入力欄やログインボタンにかぶる。

ミュート設定

入力欄が上にあるためかぶらない。

投稿画面

入力欄が上にあるためかぶらない。

YouTube

コメント画面

キーボードがボタンにかぶる。

通報モーダル

キーボードがボタンにかぶる。

GitHub

Issueのコメント画面

入力欄が丸ごとキーボードにかぶる。

一休

検索モーダル

宿泊予算の入力が丸っとかぶる。

じゃらん

検索画面

キーボードと被らないようにするためか入力UIをモーダルにして画面トップに出すように工夫されている。これなら大抵の端末やブラウザで対応できそうなので、よくできていると思う。

Amazon.co.jp

レビュー画面

入力状態になると若干のラグの後に画面下に余白ができ、入力状態が外れると同様のラグの後、画面下の余白が消えるという挙動をする。

割と凝ったJSで何かしらの計算を行い、かなり頑張って調整しているようだった。タイムラグがあるのはイベント発火もあるだろうが、キーボードの検出や画面サイズに応じた余白計算に時間がかかっているのもあるのだろう。

ここまで凝った実装をしているのは他のサイトでは見られず、Amazon.co.jp特有に見えた。なお、Amazon.comのほうは見ていない。

あとがき

この調査時点では、じゃらんとAmazon.co.jpを除き入力欄を画面の上部に配置するなどレイアウトで調整しているサイトが比較的多く、どうしてもボタンなどが隠れる傾向があるように思った。

じゃらんは強制的に画面上部に入力欄を出すようにし、Amazon.co.jpは気合でキーボードが隠れないように調整していて、腐心の跡が見られた。

なお、今回動画を作成するにあたり一部をぼかす必要があったため、やり方を調べ実践したのでAviUtlで動画の一部にモザイクをかけ、動かす方法という記事を作成し、その過程を残している。

本動画の作成過程では上手くモザイクをかけられなかったが、上記の記事を作っているときに上手く行くようになったので、本記事の動画はモザイクではなく、ぼかしとなっている。

各サービスのセッションクッキーの保持期間がどの程度か調べてみた

意外とわかりやすいサイトが少なかったので収穫はあまりないがこんな感じ。消したらログアウトされるCookieとして調べた。

サービス名 保持期間 セッションキー
GitHub 15日 user_session
Cookpad 30日 access_token_global_v2
pixiv 30日 PHPSESSID
fantia 31日 _session_id
ドリパス 2ヶ月 remember_user_token
last.fm 1年 sessionid

Amazon.co.jpやヨドバシもしばらくアクセスしていないとログアウト食らった記憶があるので、何かしらのリミットはついてそうだが、さっと調べる程度の範疇ではわからなかった。

しかしGitHubはやたらログアウト食らうとと思ったらたった15日とは…。

ドリパスはDPSSIDがなければremember_user_tokenからセッションを生成し、DPSSIDとremember_user_tokenの両方がなければログアウト状態になるようだった。DPSSIDはExpiresがSessionとなっていたため、remember_user_tokenを削除してもブラウザを落とすまではログインを継続できる。

Node.js組み込みテストランナーとJest比較メモ

JestからNode.js組み込みのテストランナーに移行する時の方法や注意点をまとめたメモ

確認環境

Env ver
Node.js 20.8.0
Jest 29.7

Node.jsの組み込みテストランナーとは

英語圏ではNode.js built-in test runnerとか呼ばれている存在で、Node.jsの組み込みテストランナーのこと。恐らくDenoのテストランナーに対抗して生まれた気配がする(Node.jsはDenoに機能追加があると真似する傾向があるため)

Node.jsの組み込みテストランナーは機能が二分されており、テストランナーとアサートに分かれている。Jestみたいにエコシステムが発達しておらず、標準ではdescribeなどはimportする必要がある。TypeScriptをテストする場合は間にレジスター[1]を嚙ます必要がある。噛まし方はswc/jestでESM, CJS混在のコードをJestを使ってテストする有力な方法は今のところ多分ないに書いた。

Jest関数との対応リスト

describe, it, beforeAll, afterAll, beforeEach, afterEach辺りは違和感がなかったが、それ以外は軒並み互換性がないので大きく書き換えが必要だと感じた。便利なMatcherは完膚なきまでに全滅している。お陰で覚えることが減ったのは逆に良くなったと感じる

なお、not始まりの機能は実際の動作を確認しておらず、Jestと同じ機能かどうかは確認していないことに留意すること

describe(name, fn), it(name, fn, timeout?), test(name, fn, timeout?)

Node.jsのTest機能では、以下となる

  • describe([name][, options][, fn])
  • it([name][, options][, fn])
  • test([name][, options][, fn])

基本的な差はないがJestにあったtimeout引数はNode.jsではoptionsパラメーターで設定するようになっている模様。今回調べるまで存在自体を知らなかったのもあり、このtimeoutがJestと同じ機能かどうかは確認していない

import { describe, it } from 'node:test';

describe('hoge', () => {
  it('hoge', () => {
    // ここにテストコード
  });

  it.todo('piyo');
});

beforeAll(fn, timeout?), afterAll(fn, timeout?), beforeEach(fn, timeout?), afterEach(fn, timeout?)

Node.jsのTest機能では、以下となる

  • before([fn][, options])
  • after([fn][, options])
  • beforeEach([fn][, options])
  • afterEach([fn][, options])

基本的な差はないがJestにあったtimeout引数はNode.jsではoptionsパラメーターで設定するようになっている模様。今回調べるまで存在自体を知らなかったのもあり、このtimeoutがJestと同じ機能かどうかは確認していない

+import { after, before, beforeEach, afterEach, describe } from 'node:test';
+
 describe('test', () => {
-  beforeAll(() => {
+  before(() => {
     console.log('before');
   });
   beforeEach(() => {
     console.log('beforeEach');
   });
   afterEach(() => {
     console.log('afterEach');
   });
-  afterAll(() => {
+  after(() => {
     console.log('after');
   });
 });

.toBe(value), .not.toBe(value)

Node.jsのTest機能では、以下となる

  • assert.strictEqual(actual, expected[, message])
  • assert.notStrictEqual(actual, expected[, message])
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
     const actual = 123;

-    expect(actual).toBe(123);
+    assert.deepStrictEqual(actual, 123);
   });
 });

.toStrictEqual(value), .not.toStrictEqual(value)

Node.jsのTest機能では、以下となる

  • assert.deepStrictEqual(actual, expected[, message])
  • assert.notDeepStrictEqual(actual, expected[, message])
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
     const actual = {
       hoge: {
         piyo: {
           id: 1,
           value: 'one'
         }
       },
       fuga: [[123, 456], 'ABC', 'EFG']
     };

-    expect(actual).toStrictEqual({
+    assert.deepStrictEqual(actual, {
       hoge: {
         piyo: {
           id: 1,
           value: 'one'
         }
       },
       fuga: [[123, 456], 'ABC', 'EFG']
     });
   });
 });

.toHaveLength(number), .toBeNull(), .toBeUndefined(), .toBeNaN()

Node.jsのTest機能では、assert.strictEqual()となる

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
     const arr = [1, 2, 3];
     const undef = undefined;
     const nil = null;
     const nan = NaN;

-    expect(arr).toHaveLength(3);
-    expect(undef).toBeUndefined();
-    expect(nil).toBeNull();
-    expect(nan).toBeNaN();
+    assert.strictEqual(arr.length, 3);
+    assert.strictEqual(undef, undefined);
+    assert.strictEqual(nil, null);
+    assert.strictEqual(nan, NaN);
   });
 });

.toBeTruthy()

Node.jsのTest機能では、以下となる

  • assert.ok(value[, message])

否定版は不明

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
-    expect(true).toBeTruthy();
-    expect({}).toBeTruthy();
-    expect([]).toBeTruthy();
-    expect(42).toBeTruthy();
-    expect('0').toBeTruthy();
-    expect('false').toBeTruthy();
-    expect(new Date()).toBeTruthy();
-    expect(-42).toBeTruthy();
-    expect(12n).toBeTruthy();
-    expect(3.14).toBeTruthy();
-    expect(Infinity).toBeTruthy();
-    expect(-Infinity).toBeTruthy();
+    assert.ok(true);
+    assert.ok({});
+    assert.ok([]);
+    assert.ok(42);
+    assert.ok('0');
+    assert.ok('false');
+    assert.ok(new Date());
+    assert.ok(-42);
+    assert.ok(12n);
+    assert.ok(3.14);
+    assert.ok(Infinity);
+    assert.ok(-Infinity);
   });
 });

.toBeInstanceOf(Class)

Node.jsのTest機能では、assert.ok()となる

結果がTruthyであればなんでもpassするので注意

+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
     const actual = new Error('hoge');

-    expect(actual).toBeInstanceOf(Error);
+    assert.ok(actual instanceof Error);
   });
 });

.toThrow, not.toThrow

Node.jsのTest機能では、以下となる

  • assert.throws(fn[, error][, message])
  • assert.doesNotThrow(fn[, error][, message])

Jestより便利になっており、Error型以外も扱えるので後述する

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
     const err = new Error('test');

-    expect(() => {
+    assert.throws(() => {
       throw err;
-    }).toThrow(err);
+    }, err);
   });
 });

Node.jsではJestと異なりError型以外も扱える

Jestの``.toThrow()`はError型以外を扱うことができず、オブジェクトをThrowするようなコードではエラーになる

describe('test', () => {
  it('test', () => {
    const obj = { id: 1, value: 'hoge' };

    // このテストは失敗する。またTypeScriptの型エラーにもなる
    expect(() => {
      throw obj;
    }).toThrow(obj);
    // このテストは失敗する。またTypeScriptの型エラーにもなる
    expect(() => {
      throw obj;
    }).toThrow({ id: 1, value: 'hoge' });
  });
});

しかしNode.jsであればこれはエラーにならない。例えば次のテストコードは成功する

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';

describe('test', () => {
  it('test', () => {
    const obj = { id: 1, value: 'hoge' };

    assert.throws(() => {
      throw obj;
    }, obj);
    assert.throws(
      () => {
        throw obj;
      },
      { id: 1, value: 'hoge' }
    );
  });
});

expect.arrayContaining(array), expect.objectContaining(object), expect.stringContaining(string)

恐らく非対称マッチャーはないので自分でロジックを書いてassert.strictEqual()で判定するしかないと思われる。元々微妙な機能だったのでやむなし

jest.spyOn(object, methodName, accessType?)

Node.jsのTest機能では、node:testからmockをimportして以下を使う

  • mock.method(object, methodName[, implementation][, options])
+import { describe, it, mock } from 'node:test';
+
 describe('test', () => {
   it('test', () => {
-    jest.spyOn(console, 'log');
+    mock.method(console, 'log');
   });
 });

本来の挙動を塞ぎたい場合

例えば以下のようにテストコードを書いた場合、execSync()が実際の挙動で動作してしまい、テストとして機能しない。

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';
import child_process, { execSync } from 'node:child_process';

const mockedExecSync = mock.method(child_process, 'execSync');

describe('execSync', () => {
  it('execSyncが正しい引数で呼ばれること', () => {
    execSync('false');

    assert.strictEqual(mockedExecSync.mock.calls[0].arguments[0], 'false');
  });
});

このような場合、以下のようにmock.method()の第三引数を指定してやると封じることができる。単体テストの観点では基本的に第三引数には空関数を入れておくのが望ましいだろう。

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';
import child_process, { execSync } from 'node:child_process';

- const mockedExecSync = mock.method(child_process, 'execSync');
+ const mockedExecSync = mock.method(child_process, 'execSync', () => {});

describe('execSync', () => {
  it('execSyncが正しい引数で呼ばれること', () => {
    execSync('false');

    assert.strictEqual(mockedExecSync.mock.calls[0].arguments[0], 'false');
  });
});

モックパターン

module.exportsされている関数のモック

import foo from 'foo';形式でmock.method()の第一引数を埋める

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';
import child_process, { execSync } from 'node:child_process';

const mockedExecSync = mock.method(child_process, 'execSync', () => {});

describe('execSync', () => {
  it('execSyncが正しい引数で呼ばれること', () => {
    execSync('false');

    assert.strictEqual(mockedExecSync.mock.calls[0].arguments[0], 'false');
  });
});

上記が正常に動作することはNode.js v20.0.0時点のコードで確認している

Global objectから生えている関数のモック

以下のようにmock.method()の第一引数にGlobal objectを設定すればよい

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';

describe('exit', () => {
  // exitが実際に走って落ちるのでmock.methodの第三引数を指定している
  const mockedExit = mock.method(process, 'exit', () => {});

  it('call exit', () => {
    process.exit(1);

    assert.strictEqual(mockedExit.mock.calls.length, 1);
  });
});
Named exportされている関数のモックは今のところ無理そう

ファイルモックをする手段がないので正攻法では無理そう
https://github.com/nodejs/help/issues/4298

2024-10-15追記

Node.js v22.3.0でテスト走行時に--experimental-test-module-mocksを渡すことで近いことができるようになった模様だが、試したところ上手く動かないし、spy的な使い方はできなさそうだ。mock.method()との組み合わせも試してみたが、上手くいかなかった。

mock.module() (nodejs.org)

ObjectやNamespaceでラップされている関数のモック

実装例(Object)

export const Hoge = {
  validateFoo() {
    // 例外を飛ばす可能性のある何かの処理
  },
  hoge() {
    Hoge.validateFoo();

    return 1;
  },
};

実装例(Namespace)

export namespace Hoge {
  export const validateFoo = () => {
    // 例外を飛ばす可能性のある何かの処理
  };
  export const hoge = () => {
    validateFoo();

    return 1;
  };
}

実装例に対するテストコード

ObjectもNamespaceも同じ書き方でテスト可能

import { describe, it } from 'node:test';
import assert from 'node:assert';
import { Hoge } from './hoge';

describe('hoge', () => {
  it('validateFooが例外をスローした場合、例外がスローされること', (t) => {
    t.mock.method(Hoge, 'validateFoo', () => {
      throw new Error('foo');
    });

    assert.throws(() => {
      Hoge.hoge();
    }, Error('foo'));
  });

  it('全ての関数が正常終了した場合、戻り値を返すこと', () => {
    const actual = Hoge.hoge();

    assert.strictEqual(actual, 1);
  });
});

.toHaveBeenCalled(), .toHaveBeenCalledTimes(number)

Node.jsのTest機能では、assert.strictEqual()でモックから生えてるやつを調べる。returnも同様の手法で実現できる

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
-    const spiedConsoleLog = jest.spyOn(console, 'log');
+    const mockedConsoleLog = mock.method(console, 'log');

     console.log();

-    expect(spiedConsoleLog).toHaveBeenCalled();
-    expect(spiedConsoleLog).toHaveBeenCalledTimes(1);
+    assert.deepStrictEqual(mockedConsoleLog.mock.calls.length, 1);
   });
 });

.toHaveBeenCalledWith(arg1, arg2, ...)

Node.jsのTest機能では、assert.strictEqual()でモックから生えてるやつを調べる。returnも同様の手法で実現できる。

Jestでは.toEqual()処理されるがNode.jsの組み込みテストランナーの場合、厳密比較ができるので便利

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
-    const spiedConsoleLog = jest.spyOn(console, 'log');
+    const mockedInfo = mock.method(console, 'log');

     console.log('test');

-    expect(spiedConsoleLog).toHaveBeenCalledWith('test');
+    assert.deepStrictEqual(mockedInfo.mock.calls[0].arguments[0], 'test');
   });
 });

jest.fn(implementation?)

Node.jsのTest機能では、以下となる

  • mock.fn([original[, implementation]][, options])
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
+// 動作確認用の関数
 const testTarget = (cbParam: string, callbackFn: (param: string) => number) => {
   return callbackFn(cbParam);
 };

 describe('test', () => {
   it('test', () => {
-    const mockFn = jest.fn((_: string) => {
+    const mockFn = mock.fn((_: string) => {
       return 5;
     });
     const actual = testTarget('hoge', mockFn);

-    expect(mockFn).toBeCalledWith('hoge');
-    expect(mockFn).toReturnWith(5);
-    expect(actual).toBe(5);
+    assert.deepStrictEqual(mockFn.mock.calls[0].arguments[0], 'hoge');
+    assert.deepStrictEqual(mockFn.mock.calls[0].result, 5);
+    assert.deepStrictEqual(actual, 5);
   });
 });

jest.useFakeTimers(fakeTimersConfig?), jest.runAllTimers()

Node.jsのTest機能では、以下となる

  • mock.timers.enable([timers])
  • mock.timers.runAll()
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
+describe('test', () => {
-  jest.useFakeTimers();
+  mock.timers.enable();

+  it('test', () => {
-    const mockFn = jest.fn();
+    const mockFn = mock.fn();
     setTimeout(() => {
       mockFn();
     }, 9999);

-    expect(mockFn).not.toHaveBeenCalled();
-    jest.runAllTimers();
-    expect(mockFn).toHaveBeenCalledTimes(1);
+    assert.deepStrictEqual(mockFn.mock.calls.length, 0);
+    mock.timers.runAll();
+    assert.deepStrictEqual(mockFn.mock.calls.length, 1);
   });
 });

jest.useRealTimers()

Node.jsのTest機能では、以下となる

  • mock.timers.reset()
+import { mock } from 'node:test';

-jest.useRealTimers();
+mock.timers.reset();

mockFn.mockClear()

Node.jsのTest機能では、以下となる

  • ctx.resetCalls()
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
-    const mockFn = jest.fn((param: string) => `<${param}>`);
+    const mockFn = mock.fn((param: string) => `<${param}>`);

     mockFn('hoge');
-    expect(mockFn).toHaveBeenCalledTimes(1);
-    expect(mockFn).toReturnWith('<hoge>');
+    assert.deepStrictEqual(mockFn.mock.calls.length, 1);
+    assert.deepStrictEqual(mockFn.mock.calls[0].result, '<hoge>');

-    mockFn.mockClear();
+    mockFn.mock.resetCalls();

-    expect(mockFn).toHaveBeenCalledTimes(0);
+    assert.deepStrictEqual(mockFn.mock.calls.length, 0);
     mockFn('piyo');
-    expect(mockFn).toHaveBeenCalledTimes(1);
-    expect(mockFn).toReturnWith('<piyo>');
+    assert.deepStrictEqual(mockFn.mock.calls.length, 1);
+    assert.deepStrictEqual(mockFn.mock.calls[0].result, '<piyo>');
   });
 });

mockFn.mockReset()

Node.jsのTest機能では、以下となる

  • mockFn.mock.restore()

振る舞いが微妙に違うため後述する

+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+
 describe('test', () => {
   it('test', () => {
-    const spiedConsoleLog = jest
-      .spyOn(console, 'log')
-      .mockImplementation((param: any) => {
-        return `<${param}>`;
-      });
+    const mockedConsoleLog = mock.method(console, 'log', (param: any) => {
+      return `<${param}>`;
+    });

     console.log('hoge');
-    expect(spiedConsoleLog).toHaveBeenCalledTimes(1);
-    expect(spiedConsoleLog).toReturnWith('<hoge>');
+    assert.deepStrictEqual(mockedConsoleLog.mock.calls.length, 1);
+    assert.deepStrictEqual(mockedConsoleLog.mock.calls[0].result, '<hoge>');

-    spiedConsoleLog.mockReset();
+    mockedConsoleLog.mock.restore();
   });
 });

JestとNode.jsでの振る舞いの差異

但しJestとNode.jsのTest機能では微妙に差異がある

例えばJestでは以下の実装が正しくPASSするが

describe('test', () => {
  it('test', () => {
    const mockFn = jest
      .spyOn(console, 'log')
      .mockImplementation((param: any) => {
        return `<${param}>`;
      });

    console.log('hoge');
    expect(mockFn).toHaveBeenCalledTimes(1);
    expect(mockFn).toReturnWith('<hoge>');

    mockFn.mockReset();

    expect(mockFn).toHaveBeenCalledTimes(0);
    console.log('piyo');
    expect(mockFn).toHaveBeenCalledTimes(1);
    expect(mockFn).not.toHaveBeenCalledWith();
    expect(mockFn).toReturnWith(undefined);
  });
});

Node.jsで以下の実装を書いても同じように機能しない

import { describe, it, mock } from 'node:test';
import assert from 'node:assert';

describe('test', () => {
  it('test', () => {
    const mockFn = mock.method(console, 'log', (param: any) => {
      return `<${param}>`;
    });

    console.log('hoge');
    assert.deepStrictEqual(mockFn.mock.calls.length, 1);
    assert.deepStrictEqual(mockFn.mock.calls[0].result, '<hoge>');

    mockFn.mock.resetCalls();
    mockFn.mock.restore();

    assert.deepStrictEqual(mockFn.mock.calls.length, 0);
    console.log('piyo');
    // 以降のテストはいずれも落ちる
    assert.deepStrictEqual(mockFn.mock.calls.length, 1);
    assert.deepStrictEqual(mockFn.mock.calls[0].result, '<piyo>');
  });
});

但しモック実装を削除したうえで再度呼び出すという行為には意味がないので、特に問題にはならないと思われる

モック機能についての備考

it([name][, options][, fn])の第三引数のコールバックの第一引数にはTestContextが入っており、これを使ってモックすることもできる

これを使う場合、スコープアウトでモックが復元されるため、例えば以下のような関数をテストするときに便利である。

実装

export namespace Hoge {
  export const validateFoo = () => {
    // 例外を飛ばす可能性のある何かの処理
  };

  export const validateBar = () => {
    // 例外を飛ばす可能性のある何かの処理
  };

  export const validateBaz = () => {
    // 例外を飛ばす可能性のある何かの処理
  };

  export const hoge = () => {
    validateFoo();
    validateBar();
    validateBaz();

    return 1;
  };
}

テストコード

import { describe, it } from 'node:test';
import assert from 'node:assert';
import { Hoge } from './hoge';

describe('hoge', () => {
  it('validateFooが例外をスローした場合、例外がスローされること', (t) => {
    t.mock.method(Hoge, 'validateFoo', () => {
      throw new Error('foo');
    });

    assert.throws(() => {
      Hoge.hoge();
    }, Error('foo'));
  });

  it('validateBarが例外をスローした場合、例外がスローされること', (t) => {
    t.mock.method(Hoge, 'validateBar', () => {
      throw new Error('bar');
    });

    assert.throws(() => {
      Hoge.hoge();
    }, Error('bar'));
  });

  it('validateBazが例外をスローした場合、例外がスローされること', (t) => {
    t.mock.method(Hoge, 'validateBaz', () => {
      throw new Error('baz');
    });

    assert.throws(() => {
      Hoge.hoge();
    }, Error('baz'));
  });

  it('全ての関数が正常終了した場合、戻り値を返すこと', () => {
    const actual = Hoge.hoge();

    assert.strictEqual(actual, 1);
  });
});

  1. 標準出力にトランスパイルした結果を出力してくれるもの ↩