
Sora Fujimoto
AI Solutions Architect
発行済み Nov 18, 2026
更新されました Nov 18, 2026 · 最小読み取り

Cypress はブラウザテスト用のプロジェクトで、Web アプリケーションを操作し、その挙動を検証するために使われる。公式 FAQ には、テストがどのようにアプリケーションとやり取りし、期待される挙動を待機するかが説明されている。CAPTCHA で保護されたフォームにはブラウザでのインタラクションとサーバ側での受け入れ結果の両方をテストする必要があるため、ここで関連してくる。
ソルバーは、すでに認可されたワークフローが画像認識に依存している場合に、その統合を限定的に確認する用途に有用である。すべての Cypress スイートで必須というわけではない。通常のアプリケーションテストでは制御された検証応答を使い、サポートしたい特定のソルバーパス向けに、別途ライブチェックを用意しておく。
この例では、CapSolver がドキュメントに記載された ImageToTextTask API を通じて画像を受け取る。Cypress は返却されたテキストを所有しているフォームに入力し、その結果を検証する。API はページをクリックしたり、チャレンジセッションを保持したり、テストの成功をアサートしたりはしない。
CAPTCHA 用語集 では検証の概念が説明されている。このチュートリアルでは、統合の仕組みを切り出すために単純な数値画像を用いる。サードパーティサイトや別種のチャレンジに対するサポートを確立するものではない。
実行環境では Node.js 24.16.0、Cypress 15.21.0、および Cypress 同梱の Electron 138 を使用した。バージョン 15.21.0 はローカルで利用可能であり、テスト実行前に検証された。このため、ここでテストされたのはこのバージョンであり、最新版であるという主張ではない。
Cypress 15.21.0 と Sharp 0.34.5 をインストールしてプロジェクトを作成する。Sharp はローカルテスト用フィクスチャの PNG を生成する。再現可能なプロジェクトファイルは server.cjs、cypress.config.cjs、cypress/e2e/captcha.cy.js の通りである。アプリケーションサーバは一つのターミナルで起動し、別のターミナルからプロジェクトディレクトリ内で Cypress を実行する。
ソルバーの API キーはプロジェクトの外にあるローカルテキストファイルに保存する。Node プロセスの環境変数 CAPSOLVER_TEST_KEY_FILE に、そのファイルの絶対パスを設定する。例では macOS のローカルフォールバックパス /private/tmp/capsolver-test-key も用意しているが、Windows など他のシステムでは必ず自分でパスを指定すること。ファイルへのアクセスは制限し、ソース管理や共有成果物からは除外する。
キーは Node タスクで読み込まれる。ブラウザテストに返されたり、Cypress.env() に置かれたり、この例のソースに含まれたりすることはない。ブラウザコンソールやページ内で実行されるテストにキーを貼り付けないこと。
このフィクスチャは数値画像を生成し、期待される解答をサーバ側に保持し、HTTP-only なチャレンジクッキーと関連付ける。ページが受け取るのは画像であって、解答をテキストフィールドや JavaScript 変数として受け取るわけではない。誤った解答を送信すると Rejected が返され、現在の正解を完全一致で送信すると Accepted が返される。
以下を server.cjs として保存し、Cypress を起動する前に Node で起動する。127.0.0.1 にバインドすることでフィクスチャをローカルに保つ。この小さなサーバはテスト用の足場であり、本番用 CAPTCHA 実装ではない。
const http=require('node:http');const crypto=require('node:crypto');const sharp=require('sharp');
const challenges=new Map();
const server=http.createServer(async(req,res)=>{
if(req.method==='GET' && req.url==='/'){
const token=crypto.randomBytes(16).toString('hex'); const answer=String(crypto.randomInt(100000,999999));
challenges.set(token,answer);
const png=await sharp(Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="260" height="90"><rect width="260" height="90" fill="white"/><text x="15" y="62" font-family="Arial" font-size="48" fill="black">${answer}</text></svg>`)).png().toBuffer();
res.writeHead(200,{'Content-Type':'text/html','Set-Cookie':`challenge=${token}; HttpOnly; SameSite=Strict`,'Cache-Control':'no-store'});
res.end(`<html><body><h1>Owned CAPTCHA QA fixture</h1><img id="captcha" alt="Numeric test challenge" src="data:image/png;base64,${png.toString('base64')}"><form><label>Answer<input id="answer" name="answer"></label><button>Submit</button></form><p id="result"></p><script>document.querySelector('form').onsubmit=async e=>{e.preventDefault();const r=await fetch('/verify',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({answer:document.querySelector('#answer').value})});document.querySelector('#result').textContent=await r.text();};</script></body></html>`);return;
}
if(req.method==='POST' && req.url==='/verify'){
let body=''; for await(const chunk of req)body+=chunk;
const token=(req.headers.cookie||'').match(/challenge=([a-f0-9]+)/)?.[1];
let value;try{value=JSON.parse(body).answer;}catch{res.writeHead(400);res.end('Bad request');return;}
const expected=challenges.get(token);const accepted=challenges.has(token) && expected===value;console.log(JSON.stringify({kind:'validation',expected,submitted:value,hasSession:!!token,accepted}));challenges.delete(token);
res.writeHead(accepted?200:422,{'Content-Type':'text/plain'});res.end(accepted?'Accepted':'Rejected');return;
}
res.writeHead(404);res.end('Not found');
});server.listen(18761,'127.0.0.1',()=>console.log('Owned QA fixture listening on 127.0.0.1:18761'));
このサーバは、解答が送信されるとチャレンジを消費する点に注意すること。これにより、古い解答は後の試行には使えなくなり、誤って再利用してしまう問題を発見しやすくなる。実際のアプリケーションでは異なるライフサイクル規則を取るかもしれないので、そのアプリケーションのドキュメント化された挙動に合わせてテストを調整すること。
Cypress の cy.task のドキュメント に境界が定義されている。テストはブラウザで実行され、登録されたハンドラは Node.js 上で実行される。引数と戻り値はシリアライズされたデータとしてその境界を越える。
以下の設定を cypress.config.cjs として保存する。ペイロードでは、CapSolver のドキュメントにある clientKey、task.type、画像 body フィールドを使用している。リクエストの周囲にあるカスタムコードはタイムアウトと応答検証を扱うものであり、アプリケーション用アダプタであって公式の Cypress–CapSolver パッケージではない。
const { defineConfig } = require('cypress');
const fs = require('node:fs');
module.exports = defineConfig({
video: false, screenshotOnRunFailure: false, allowCypressEnv: false,
e2e: { baseUrl: 'http://127.0.0.1:18761', supportFile: false,
setupNodeEvents(on) {
on('task', {
async solveImage(body) {
const keyPath=process.env.CAPSOLVER_TEST_KEY_FILE || '/private/tmp/capsolver-test-key';
if (!fs.existsSync(keyPath)) throw new Error('Missing local solver key file; no live solve was attempted');
const clientKey=fs.readFileSync(keyPath,'utf8').trim();
if (!clientKey) throw new Error('Empty solver key file');
const response=await fetch('https://api.capsolver.com/createTask',{
method:'POST',headers:{'Content-Type':'application/json'},
body:JSON.stringify({clientKey,task:{type:'ImageToTextTask',body}}),
signal:AbortSignal.timeout(30000)
});
if(!response.ok) throw new Error(`Solver HTTP ${response.status}`);
const data=await response.json();
if(data.errorId!==0) throw new Error(`Solver task failed: ${data.errorCode || data.errorId}`);
if(typeof data.solution?.text!=='string' || !data.solution.text) throw new Error('No recognized text returned');
fs.appendFileSync('solve-evidence.jsonl',JSON.stringify({timestamp:new Date().toISOString(),taskType:'ImageToTextTask',status:data.status,solutionText:data.solution.text})+'\n');
return data.solution.text;
},
keyAvailable() { return fs.existsSync(process.env.CAPSOLVER_TEST_KEY_FILE || '/private/tmp/capsolver-test-key'); }
});
}
}
});
画像ボディは、データ URI プレフィックスを除いた Base64 である。ImageToTextTask は認識結果を直接返すため、この例ではポーリングループを追加していない。別の CAPTCHA タスクに変更する場合は、そのタスク独自の応答仕様に従い、この同期フローをそのままコピーしないこと。
ハンドラはこの合成フィクスチャからのタイムスタンプ、タスクタイプ、ステータス、および認識されたテキストだけを記録する。API キーや生のリクエストは記録しない。自分の環境では、認識テキストをログに残すことが適切かどうかを判断し、不要になったらその診断記録を削除すること。
CapSolver ボーナスコードを利用する
自動化の予算をすぐに増やそう!
CapSolver アカウントにチャージする際にボーナスコード CAP26 を使用すると、すべてのチャージに対して追加で 5% ボーナス が無制限に付与される。
今すぐ CapSolver ダッシュボード で引き換えよう。
以下を cypress/e2e/captcha.cy.js として保存する。最初のテストは誤答が拒否されることを確認する。2 つ目は Node タスク境界を行き来できることを確認する。3 つ目は現在のチャレンジ画像を読み取り、実際のソルバーを呼び出し、返却された値を入力してアプリケーションの受け入れを確認する。
describe('Owned image CAPTCHA form', () => {
it('rejects an incorrect answer at the application boundary', () => {
cy.visit('/');
cy.get('#answer').type('incorrect');
cy.get('button').click();
cy.get('#result').should('have.text','Rejected');
});
it('runs the Node task boundary without exposing the solver key', () => {
cy.task('keyAvailable').then(value => expect(value).to.be.a('boolean'));
});
it('submits a live solver result for the current challenge', function () {
cy.task('keyAvailable').then(available => {
if(!available) this.skip();
cy.visit('/');
cy.get('#captcha').should('have.attr','src').then(src => {
const body=src.split(',')[1];
return cy.task('solveImage',body,{timeout:40000,log:false});
}).then(text => {
cy.get('#answer').type(text,{log:false,parseSpecialCharSequences:false});
cy.get('button').click();
cy.get('#result').should('have.text','Accepted');
});
});
});
});
プロジェクトディレクトリから node node_modules/cypress/bin/cypress run --browser electron を実行する。キー ファイルが存在しない場合、ライブケースは意図的に pending になる。pending がある緑の実行は、有料 API 統合が正常に動作したという証拠にはならない。CI でライブ統合ゲートを設ける場合は、そのケースが実行されることと、関連テストがスキップされていないことを条件にすること。
入力コマンドでは特殊文字のパースを無効化し、認識されたテキストをそのまま入力できるようにしている。Cypress の type リファレンス にこのオプションが記載されている。テストもハンドラも、パスさせるために勝手に大文字小文字を変えたり文字を削除したりはしない。
この例は意図的に数値のみである。CapSolver の 画像 CAPTCHA 統合ガイド には、Image To Text 認識は大文字小文字の区別をサポートしないと記載されている。大文字小文字を厳密に一致させる混在ケースのチャレンジには、このワークフローを再利用する前に別途能力の確認が必要となる。
2026 年 11 月 18 日の最終実行では、3 件のテストが 3 件ともパスし、失敗も pending もなかった。ライブソルバーはフィクスチャのサーバが保持していたものと同じ 6 桁の値を返し、アプリケーションは Accepted を返した。誤答テストでは別途 Rejected が確認されている。
それ以前のライブ試行では、認識結果は受け取れたものの、アプリケーションアサーションに失敗した。その試行では期待値と送信値を記録していなかったため、正確な原因は特定されていない。後続の実行ではその証跡を追加し、一致した結果を確認した。値を一致させるための認識結果の変換は追加していない。
これらの観察から、この制御された例においては、リクエスト、Cypress タスク、ブラウザ入力、セッション、およびアプリケーションアサーションが連携して動作し得ることが示される。ただし、精度率、サービスレベル保証、本番サイトでの挙動を示すものではない。失敗した実行も評価履歴に残し、ソルバーを評価する際に成功した試行だけを報告しないこと。
まずは失敗した境界から確認する。キー ファイルがないとライブリクエストは行われない。HTTP エラーはリクエストが正常に完了しなかったことを示す。非 0 の API エラーは、ハンドラがその応答を認識テキストとして扱ってはならないことを意味する。文字列が返されているのに Rejected となった場合は、アプリケーションレベルの調査が必要である。
最後のケースでは、元の画像、返却されたテキスト、実際に送信された値、およびチャレンジクッキーが現在のフォームとまだ関連付けられているかを確認する。ページがチャレンジを更新している場合は、画像を取り直すこと。以前のチャレンジからの解答を送り続けたり、制限のないリトライループの中に有料呼び出しを隠したりしないこと。
API が文字列を返したことだけをアサートするのも有用だが、それだけでは不十分である。最終的なフォームアサートを残しておき、セレクタの破損、チャレンジの期限切れ、誤答などでテストが明示的に失敗するようにしておくこと。
ここで示したパターンは、自分が管理しているアプリケーションに対し、小さく明示的なソルバー統合チェックを行うために使うこと。クレデンシャルは Node 側に保持し、画像タスクはそのドキュメントどおりの能力に合わせ、受信側フォームの結果を検証する。CapSolver は認識ステップを提供し、Cypress は最終的なテスト結果を可視化する。
Q: Cypress には組み込みの CAPTCHA ソルバーが含まれますか?
この例はそれに依存していない。ここでは Cypress の汎用的な Node タスク機構を使って、別の認識 API を呼び出している。
Q: このコードを reCAPTCHA や Cloudflare チャレンジに使用できますか?
そのままの形では使用できません。このコードは画像を ImageToTextTask に送信し、認識されたテキストを入力するものです。ほかの種類のチャレンジには、それぞれ固有の入力・出力仕様とアプリケーションへの統合方法が文書化されています。
Q: なぜキーなしでライブテストが保留 (pending) のままになるのですか?
このサンプルコードは、キー用ファイルが存在しない場合、有料コールを明示的にスキップするようになっています。保留 (pending) と表示されるのは、ライブ統合がテストされていないことを意味し、それを成功した解決として数えてはいけません。
Q: 1 回チャレンジに成功しただけで高い精度を主張できますか?
できません。その例について動作経路が有効であることを確認したにすぎません。統計的な主張を行う前に、代表的な入力を評価し、拒否された試行も保存しておく必要があります。
Q: これは公式の Cypress 用統合パッケージですか?
いいえ。これは公式の Cypress タスク API と、文書化されている CapSolver の ImageToTextTask エンドポイントを利用したテスト済みのアダプターです。ローカル形式は独自の QA 用足場コードです。

Sora Fujimoto
AI Solutions Architect
Connecting agents, browsers, and APIs into one workflow.
著者について
