.. _test data: .. _general parsing rules: .. _Test data syntax: テストデータの形式 ====================== この節では、 Robot Framework のテストデータの形式を大まかに解説します。 実際のテストケースやテストスイートなどの作成方法は、後の節で述べます。 .. contents:: :depth: 2 :local: ファイルとディレクトリ ------------------------ テストケースを階層的にアレンジする方法は、以下の通りです: - テストケースは :ref:`テストケースファイル ` の中に書きます。 - テストケースファイル一つが、自動的にファイル中の全てのテストケースからなる :ref:`テストスイート ` になります。 - テストケースファイルの入ったディレクトリは、より高水準のテストスイートとなります。 この :ref:`テストスイートディレクトリ ` の中には、ディレクトリ内のテストファイルによるテストスイートが、サブテストスイートとして入っています - テストスイートディレクトリの中に、別のテストスイートディレクトリを配置できます。 その場合、階層構造は必要に応じて深くなっていきます。 - テストスイートディレクトリに、特殊な :ref:`初期化ファイル ` を置くことがあります。 上のルールの他に、テストに関係する以下のファイルがあります: - :ref:`ライブラリファイル ` には、他のテストを定義するための低水準のキーワードが入っています。 - :ref:`リソースファイル ` には、 :ref:`変数 ` と、高水準の `ユーザ定義のキーワード ` が入っています。 - :ref:`変数ファイル ` は、リソースファイルよりも柔軟なやりかたで変数を生成する方法を提供します。 .. _Supported file formats: サポートするファイル形式 -------------------------- Robot Framework のテストデータは、 HTML, タブ区切りの値(TSV)、プレーンテキスト、 reStruncturedText (reST) フォーマットのいずれかを使ったテーブル形式です。 それぞれのフォーマットの詳細と長所や短所については、以降の節で個々に説明していきます。 どのフォーマットを使うべきかは状況次第ですが、特に事情がないのなら、プレーンテキストを推奨します。 Robot Framework は、ファイルの拡張子に基づいて、テストデータのパーザを切り替えます。拡張子の大小文字は区別しません。 認識する拡張子は、 :file:`.html`, :file:`.htm`, :file:`.xhtml` が HTML, :file:`.tsv` が TSV, :file:`.txt` と :file:`.robot` がプレーンテキスト、 :file:`.rst` と :file:`.rest` が reStructuredText です。 テストの書き方を学びやすくするため、 HTML と TSV 形式には特別なテストデータ形式があります。 .. Different `test data templates`_ are available for HTML and TSV .. formats to make it easier to get started writing tests. .. note:: 拡張子 :file:`.robot` のプレーンテキストファイルへの対応は Robot Framework 2.7.6 以降でサポートしています。 .. _HTML format: HTML 形式 ~~~~~~~~~~~ HTML ファイルを使うと、テーブルのフォーマットができ、その前後に自由にテキストを書けます。 テストケースファイルに追加の情報を記載できるので、様式に沿ったテスト仕様書にできます。 HTML フォーマットの大きな問題は、普通のテキストエディタで編集するのが楽ではないことです。 もう一つの問題は、 HTML にすると、差分の中にテストデータに加えて HTML の構文が交じるので、バージョン管理システムでの管理がしづらいことです。 HTML ファイルでは、テストデータは個別のテーブルで定義します (下の例を参照)。 Robot Framework は :ref:`テストデータテーブル ` を、テーブルの最初のセルのテキストで判別します。 テーブルの外にある情報は、全て無視されます。 .. table:: HTML 形式の書き方 :class: example ============ ================ ======= ======= Setting Value Value Value ============ ================ ======= ======= Library OperatingSystem \ ============ ================ ======= ======= .. table:: :class: example ============ ================ ======= ======= Variable Value Value Value ============ ================ ======= ======= ${MESSAGE} Hello, world! \ ============ ================ ======= ======= .. table:: :class: example ============ =================== ============ ============= Test Case Action Argument Argument ============ =================== ============ ============= My Test [Documentation] Example test \ Log ${MESSAGE} \ My Keyword /tmp \ Another Test Should Be Equal ${MESSAGE} Hello, world! ============ =================== ============ ============= .. table:: :class: example ============ ====================== ============ ========== Keyword Action Argument Argument ============ ====================== ============ ========== My Keyword [Arguments] ${path} \ Directory Should Exist ${path} ============ ====================== ============ ========== テストデータの編集 ''''''''''''''''''''' HTML ファイルのテストデータはどんなエディタでも編集できますが、テーブルを表の形で見られるグラフィカルなエディタがお勧めです。 RIDE_ は HTML を読み書きできますが、残念ながら、 HTML によるフォーマットが失われ、テストケーステーブルの外にある情報が欠落することがあります。 .. _Encoding and entity references: エンコーディングとエンティティ参照 '''''''''''''''''''''''''''''''''''' Robot Framework は HTML エンティティ参照 (`ä` など) をサポートしています。 さらに、どんなエンコーディングも、データファイル中で指定している限り使えます。 通常の HTML ファイルには、以下のような META エレメントが必要です:: XHTML ファイルの場合は、以下のように XML のプリアンブルが必要です:: エンコーディングを指定しない場合、 Robot Framework はデフォルト値として ISO-8859-1 (latin-1) を使います。 .. _TSV format: TSV 形式 ~~~~~~~~~~ TSV ファイルは表計算プログラムで編集でき、構文が簡単なためプログラムで簡単に生成できます。 普通のテキストエディタでも編集しやすく、バージョン管理システムでの管理も楽です。 とはいえ、同じ理由で選ぶのであれば、 :ref:`プレーンテキスト形式 ` の方がもっと向いています。 TSV 形式は、ほぼ HTML と同じ用途のテストデータに使えます。 TSV ファイルの中では、全テストデータが一つの大きなテーブルの中に入っています。 各々の :ref:`テストデータテーブル ` は、「一つ以上のアスタリスク (`*`)、テーブル名、アスタリスク」が書かれている場所から始まります。ただし、テーブル名の後のアスタリスクは省略できます。 最初に認識されたテーブルよりも前にかかれている内容は、 HTML データのテーブルの外のデータと同様、無視されます。 .. table:: TSV 形式の書き方 :class: tsv-example ============ ======================= ============= ============= \*Setting* \*Value* \*Value* \*Value* Library OperatingSystem \ \ \*Variable* \*Value* \*Value* \*Value* ${MESSAGE} Hello, world! \ \ \*Test Case* \*Action* \*Argument* \*Argument* My Test [Documentation] Example test \ Log ${MESSAGE} \ My Keyword /tmp \ Another Test Should Be Equal ${MESSAGE} Hello, world! \ \ \*Keyword* \*Action* \*Argument* \*Argument* My Keyword [Arguments] ${path} \ Directory Should Exist ${path} ============ ======================= ============= ============= テストデータの編集 ''''''''''''''''''''' TSV ファイルの作成や編集は、Microsoft Excel をはじめほとんどの表計算ソフトでできます。 ファイルを保存するときに、タブ区切り形式のフォーマットにして、ファイルの拡張子を :file:`.tsv` にセットしてください。 編集するときは、オートコレクトをオフにして、ファイル中の全ての値をプレーンテキストで保存する設定にしてください。 TSV ファイルは、テキストエディタでも比較的容易に編集できます。 特に、エディタがタブとスペースを視覚的に区別できると便利です。 RIDE_ は TSV 形式をサポートしています。 Robot Framework は、 TSV データを解析するときに、全ファイルコンテンツを行に分割して、さらに各行をタブ文字で分割します。 表計算ソフトによっては、(`"my value"` のように) セルの値をクオートで囲うことがあり、 Robot Framework はクオートを除去します。 データ中のクオートが2重でエスケープされている場合 (例: `"my ""quoted"" value"`) もありますが、これも正しく扱います。 表計算ソフトで TSV データを作成する場合はこうした挙動を気にする必要はありませんが、プログラムでデータを生成するときには、表計算と同じクオートの取扱いが必要なので注意してください。 エンコーディング ''''''''''''''''''' TSV ファイルは、常に UTF-8 エンコーディングとみなします。 ASCII は UTF-8 のサブセットなので、 ASCII エンコーディングもサポートしています。 .. _Plain text format: プレーンテキスト形式 ~~~~~~~~~~~~~~~~~~~~~ プレーンテキスト形式は、編集がとても簡単で、どんなテキストエディタでも編集でき、バージョン管理システムでも容易に扱えます。 こうした諸々の長所から、 Robot Framework で最もよく使われているデータ形式です。 プレーンテキスト形式は、技術的にはどちらかといえば :ref:`TSV形式 ` に近いですが、セルの区切り方が違います。 TSV 形式がタブを使うのに対して、プレーンテキスト形式は 2 個以上のスペースか、パイプ文字の両側にスペースを入れたもの ( :codesc:`\ |\ ` ) で区切ります。 :ref:`テストデータテーブル ` は、TSVと同様、「一つ以上のアスタリスク (`*`)、テーブル名、アスタリスク」が書かれている場所から始まります。余分なアスタリスクとスペースがヘッダにあっても無視されるので、 `*** Settings ***` と `*Settings` は同じです。 また、 TSV と同様、最初に認識したテーブルよりも前の内容は無視されます。 プレーンテキスト形式では、タブは自動的に 2 スペースに変換されます。そのため、 TSV と同様、タブを区切り文字として使えます。 ただし、TSV 形式ではタブは常に区切り文字ですが、プレーンテキスト形式では、複数のタブ文字が連続すると合わせて一つの区切りとみなします。 .. _Space separated format: スペース区切り方式 '''''''''''''''''''''' スペース区切り方式では、区切りに使うスペースの数は 2文字以上なら何個つづけてもかまいません。 そのため、データを見栄え良く並べられます。 これはテキストエディタで TSV 形式を編集するより好都合です。 というのも、TSV は列の並びを完全にはコントロールできないからです。 .. sourcecode:: robotframework *** Settings *** Library OperatingSystem *** Variables *** ${MESSAGE} Hello, world! *** Test Cases *** My Test [Documentation] Example test Log ${MESSAGE} My Keyword /tmp Another Test Should Be Equal ${MESSAGE} Hello, world! *** Keywords *** My Keyword [Arguments] ${path} Directory Should Exist ${path} スペースを区切り文字として使っているので、空のセルは `${EMPTY}` という特殊な変数か、バックスラッシュ一文字で :ref:`エスケープ ` せねばなりません。 また、 :ref:`空白文字の扱い ` が他のテストデータと違っていて、テストデータの前後にスペースがある場合や、データの中に2つ以上続くスペースがある場合は常にエスケープせねばなりません。 .. tip:: キーワードと引数の間は、4文字以上スペースを入れるよう勧めます。 .. _pipe separated format: スペース・パイプ区切り方式 ''''''''''''''''''''''''''''''' スペース区切り方式の最大の問題は、キーワードと引数の区切りが見づらいことです。 特に、引数がたくさんあるキーワードや、引数にスペースが入る場合には厄介です。 そんな時は、パイプとスペースを使った区切りの方が、セルの境界がはっきり判ります。 .. sourcecode:: robotframework | *Setting* | *Value* | | Library | OperatingSystem | | *Variable* | *Value* | | ${MESSAGE} | Hello, world! | | *Test Case* | *Action* | *Argument* | | My Test | [Documentation] | Example test | | | Log | ${MESSAGE} | | | My Keyword | /tmp | | Another Test | Should Be Equal | ${MESSAGE} | Hello, world! | *Keyword* | | My Keyword | [Arguments] | ${path} | | Directory Should Exist | ${path} プレーンテキスト形式のテストデータには、スペース区切り方式とスペース・パイプ区切り方式を混在させられます。 ただし、一つの行の中ではどちらかに揃えねばなりません。 パイプ・スペース方式の行はパイプで開始せねばなりませんが、行末のパイプは省略可能です。 行の先頭を除き、パイプ文字の両側には必ず一つ以上スペースがなければなりません。 ただし、データの並びをはっきりさせるために、パイプの位置を他の行と揃える必要はありません。 パイプ・スペース方式では、(:ref:`末尾の空白セル ` を除き、) 空のセルをエスケープする必要はありません。 唯一、エスケープを考慮しなければならないのは、パイプの両側にスペースがあるような文字列を書きたい時で、その場合はバックスラッシュでエスケープしてください: .. sourcecode:: robotframework | *** Test Cases *** | | | | | Escaping Pipe | ${file count} = | Execute Command | ls -1 *.txt \| wc -l | | | Should Be Equal | ${file count} | 42 | .. Editing and encoding: 編集とエンコーディング '''''''''''''''''''''''' プレーンテキスト形式が HTML や TSV に対して最も優れているのは、普通のテキストエディタでの編集がとても簡単なことです。 ほとんどのエディタや IDE (Eclipse, Emacs, Vim, TextMate など) には、 Robot Framework のテストデータを編集するための構文ハイライト用プラグインがあり、キーワード保管などの機能も備えています。 RIDE_ もプレーンテキスト形式をサポートしています。 TSV 形式のテストデータと同様、プレーンテキスト形式のファイルも UTF-8 エンコーディング想定です。 従って、 ASCII エンコーディングのファイルもサポートしています。 .. _Recognized extensions: Robot Framework の認識する拡張子 '''''''''''''''''''''''''''''''''' Robot Framework 2.7.6 から、プレーンテキスト形式のテストデータファイルの拡張子として、従来の :file:`.txt` に加えて :file:`.robot` のサポートを追加しました。 新しい拡張子を使えば、他のプレーンテキストファイルとテストデータを区別しやすくなります。 reStructuredText 形式 ~~~~~~~~~~~~~~~~~~~~~~~ reStructuredText_ (reST) は、読みやすさを重視したプレーンテキストのマークアップ方式で、 Python プロジェクトのドキュメンテーションによく使われています (Python のソースコード自体にも、ユーザガイドにも)。 reST ドキュメントは HTML にコンパイルされることが多いですが、他の出力フォーマットもサポートしています。 reST を Robot Framework に使うと、簡単なテキストフォーマットのファイル中に、巧みにフォーマットしたドキュメントとテストデータを混在させられます。 ファイルは単純なテキストエディタでも簡単に編集でき、差分ツールやソースコード管理システムで扱えます。 プレーンテキストと HTML フォーマットの長所をうまく合わせたフォーマットといえるでしょう。 reST ファイルを使う場合、テストデータの定義方法は2つあります。 :ref:`コードブロック ` を使って、 :ref:`プレーンテキスト形式 ` でテストケースを書く方法と、 :ref:`HTML 形式 ` と同じように、 :ref:`テーブル ` で書く方法です。 .. note:: reST ファイルのテストデータを Robot Framework で扱うには、 Python の docutils_ モジュールが必要です。 .. Using code blocks: コードブロック方式 ''''''''''''''''''''' reStructuredText のドキュメントには、コードブロックと呼ばれるマークアップにコードサンプルを入れられます。 ドキュメントを HTML などのフォーマットに変換すると、コードブロックの内容は Pygments_ などでハイライト表示されます。 標準の reST の書き方では、コードブロックは `code` ディレクティブで開始します。 Sphinx_ を使っている場合は、 `code-block` か `sourcecode` ディレクティブを使います。 ディレクティブの最初の引数には、コードブロック内のコードのプログラミング言語名を指定できます。 例えば、以下のコードブロックには、それぞれ Python と Robot Framework のコードサンプルが入っています: .. sourcecode:: rest .. code:: python def example_keyword(): print 'Hello, world!' .. code:: robotframework *** Test Cases *** Example Test Example Keyword Robot Framework に reStructuredText ファイルを処理させると、まず `code`, `code-block`, `sourcecode` ブロックのうち、 Robot Framework のテストデータが入ったものを探します。 コードブロックが見つかったら、テストデータをメモリ上のファイルに書き出して実行します。コードブロック外の情報は全て無視します。 コードブロック内のテストデータは、 :ref:`プレーンテキスト形式 ` で書かねばなりません。 以下の例のように、スペース区切り方式、スペース・パイプ区切り方式の両方をサポートしています。 .. sourcecode:: rest サンプル ---------- このテキストは、コードブロックの外にあるので無視されます。 .. code:: robotframework *** Settings *** Library OperatingSystem *** Variables *** ${MESSAGE} Hello, world! *** Test Cases *** My Test [Documentation] Example test Log ${MESSAGE} My Keyword /tmp Another Test Should Be Equal ${MESSAGE} Hello, world! このテキストも、コードブロックの外にあるので無視されます。 上のブロックはスペース区切り方式のプレーンテキストで、下のブロックは パイプ・スペース区切り方式です。 .. code:: robotframework | *** Keyword *** | | | | My Keyword | [Arguments] | ${path} | | | Directory Should Exist | ${path} | .. note:: このフォーマット内では、バックスラッシュを使った :ref:`エスケープ ` を使えます。 reST のテーブルを使う時のように、2重のエスケープは要りません。 .. note:: コードブロックでテストデータを書けるようになったのは、 Robot Framework 2.8.2 からです。 .. _Using tables テーブル方式 '''''''''''''' reStructuredText ドキュメント中に、 Robot Framework のデータの入ったコードブロックがなければ、Robot Framework は、 :ref:`HTML 形式 ` と同様、テーブルにテストデータが入っているものとみなし、ドキュメントをメモリ上で HTML にコンパイルしてから、通常の HTML ファイルのテストデータと同じように解析します。 Robot Framework は、テーブルの最初のセルで :ref:`テストデータテーブル ` を認識し、テーブルの外にある情報を無視します。 以下に、 4 つのテストデータを、シンプルなテーブル形式と、グリッド形式で示します: .. sourcecode:: rest Example ------- このテキストは、コードブロックの外にあるので無視されます。 ============ ================ ======= ======= Setting Value Value Value ============ ================ ======= ======= Library OperatingSystem ============ ================ ======= ======= ============ ================ ======= ======= Variable Value Value Value ============ ================ ======= ======= ${MESSAGE} Hello, world! ============ ================ ======= ======= ============= ================== ============ ============= Test Case Action Argument Argument ============= ================== ============ ============= My Test [Documentation] Example test \ Log ${MESSAGE} \ My Keyword /tmp \ Another Test Should Be Equal ${MESSAGE} Hello, world! ============= ================== ============ ============= このテキストも、コードブロックの外にあるので無視されます。 上はシンプルなテーブル定義の書き方で、下はグリッドを使った書き方です。 +-------------+------------------------+------------+------------+ | Keyword | Action | Argument | Argument | +-------------+------------------------+------------+------------+ | My Keyword | [Arguments] | ${path} | | +-------------+------------------------+------------+------------+ | | Directory Should Exist | ${path} | | +-------------+------------------------+------------+------------+ .. note:: シンプルなテーブル定義の場合、各行の最初のカラムが空のときはエスケープが必要です。 上の例では :codesc:`\\` を使っていますが `..` も使えます。 .. note:: reST ではバックスラッシュ文字をエスケープ文字として使っています。 そのため、バックスラッシュを Robot Framework に認識させたい場合には、 `\\` のように、もう一つバックスラッシュが必要です。 例えば、改行文字を表現するときは、 `\\n` です。 Robot Framework のデータは、バックスラッシュを :ref:`エスケープ ` に使うので、 reST のテーブルの中で、リテラルとしてバックスラッシュを使いたい場合には、さらにエスケープして `c:\\\\temp` のように書かねばなりません。 テストをランする度に毎回 reST で HTML ファイルを生成していると、明らかにオーバヘッドを生じます。 問題になるようなら、外部ツールを使って reST ファイルを予め HTML に変換しておき、生成したファイルを Robot Framework に読ませるとよいでしょう。 .. _Editing and encoding: 編集とエンコーディング '''''''''''''''''''''''' reStructuredText 形式のテストデータはどんなテキストエディタでも編集でき、多くのテキストエディタが reST の構文ハイライトをサポートしています。 残念ながら、 RIDE_ は reST をサポートしていません。 reST ファイルでは、非 ASCII 文字を UTF-8 エンコーディングで保存せねばなりません。 .. _Syntax errors in reST source files: reST ソースファイルの構文エラー '''''''''''''''''''''''''''''''''' reStructuredText ドキュメントが構文的に正しくない場合 (テーブルの書式がおかしい場合など) は、 reST ファイルの解析に失敗するため、テストケースを抽出できないことがあります。単一の reST ファイルを実行しているときには、 Robot Framework はコンソールにエラーを出力しますが、ディレクトリ単位で実行しているときには、解析エラーは無視されてしまいます。 Robot Framework 2.9.2 からは、 `SEVERE` レベルに達しないエラーを無視することで、 reST 文書中に標準でサポートしないディレクティブやマークアップがあっても、ノイズの影響を受けないようにしました。 この仕様のため、 reST マークアップのエラーはテストランナには隠蔽されますが、 docutils でファイルを普通にコンパイルするとエラーが表示されるので注意してください。 .. _Test data tables: テストデータテーブル ----------------------- テストデータは、以下の 4 つのタイプのテーブルで構成されています。 各々のテストデータテーブルは、テーブルの最初のセルの値で区別します。 Robot Framework が認識するテーブル名は、 `Settings` (設定)、 `Variables` (変数), `Test Cases` (テストケース), `Keywords` (キーワード) です。 テーブル名は大小文字の区別をせず、 `Setting` や `Test Case` のように単数形でもかまいません。 .. table:: テストデータテーブルとその役割 :class: tabular +--------------+------------------------------------------------+ | テーブル | 用途 | +==============+================================================+ | Settings | | 1) :ref:`テストライブラリ `, | | | :ref:`リソースファイル `, | | | :ref:`変数ファイル ` | | | の取り込み | | | | 2) :ref:`テストスイート ` や | | | :ref:`テストケース` のメタデータの定義 | +--------------+------------------------------------------------+ | Variables | テストデータ中で使う :ref:`変数 ` | | | の定義 | +--------------+------------------------------------------------+ | Test Cases | 定義済みのキーワードを使った | | | :ref:`テストケース定義 ` | +--------------+------------------------------------------------+ | Keywords | 既存の低水準キーワードを使った | | | :ref:`キーワード定義 ` | +--------------+------------------------------------------------+ .. _Rules for parsing the data: テストデータ解析のルール -------------------------- .. _comment: .. _Ignored data: コメント、無視される情報 ~~~~~~~~~~~~~~~~~~~~~~~~~ Robot Framework がテストデータを解析する際、以下の内容は無視されます: - 最初のセルに :ref:`テストデータテーブル ` の名前が入っていないテーブル。 - テストデータのテーブルで、最初の行の最初のセル以外の内容。 - 最初に見つかったテストデータテーブルより前に書かれている情報全て。 テーブルの間に何か記述できるデータフォーマットの場合は、その内容も無視されます。 - テーブルの見栄えをよくするなどの目的で挿入されている空の行。 - 行末側の空のセルで、 :ref:`エスケープ ` していないもの全て。 - :ref:`エスケープ ` に使っていないバックスラッシュ (:codesc:`\\`) 全て。 - セル中の値がハッシュ文字 (`#`) で始まる場合、ハッシュ文字より後ろの内容。 この機能を使って、テストデータのコメントを書けます。 - HTML/reST 中の全マークアップ。 Robot Framework がテストデータ中の情報を無視した場合、その情報は結果レポートから一切アクセスできません。 また、 Robot Framework と組み合わせて使うツールのほとんどが、同じようにデータを無視します。 Robot Framework の出力に何らかの情報を表示したいなら、テストケースやテストスイートにドキュメントやメタデータを付与するか、 :ref:`組み込み ` キーワードの :name:`Log` や :name:`Comment` を使ってログに出力してください。 .. _Handling whitespace: 空白文字の扱い ~~~~~~~~~~~~~~~~~~~ Robot Framework は、空白文字を HTML のソースコード中の空白文字と同じように扱います。すなわち: - 改行、復帰、タブはスペースに変換される。 - セルの先頭や末尾に入っている空白文字は全て無視する。 - スペースが複数個並んでいる時は、ひとつのスペースに置き換える。 加えて、非改行スペースは普通のスペースに置き換わります。 これは、普通のスペースの代わりに誤って非改行スペースを使ってしまった場合に、検出が難しいエラーとなるのを防ぐためです。 セルの先頭や末尾のスペース、複数個並んだスペースが必要な場合は、 :ref:`エスケープ ` が必要です。 改行、復帰、タブ、非改行スペースは、それぞれ `\n`, `\r`, `\t`, `\xA0` といった :ref:`エスケープシーケンス ` で入力できます。 .. _Escaping: エスケープ ~~~~~~~~~~~ Robot Framework のテストデータでエスケープに使う文字は、バックスラッシュ (:codesc:`\\`) です。 :ref:`組み込み変数 ` の `${EMPTY}` および `${SPACE}` もよく使われます。 この節では、それぞれのエスケープメカニズムについて解説します。 .. _Escaping special characters: 特殊文字のエスケープ '''''''''''''''''''''' バックスラッシュを使って特殊文字をエスケープすることで、リテラルとしてその文字を表現できます。 .. table:: 特殊文字のエスケープ :class: tabular ====== ========================================================== ============================ 文字 意味 例 ====== ========================================================== ============================ `\$` :ref:`スカラー変数 ` の開始記号でない `\${notvar}` `\@` :ref:`リスト変数 ` の開始記号でない `\@{notvar}` `\%` :ref:`環境変数 ` の開始記号でない `\%{notvar}` `\#` :ref:`コメント ` の開始記号でない `\# not comment` `\=` :ref:`名前付き引数 ` の記法でない `not\=named` `\|` :ref:`パイプ区切り ` でない `| Run | ps \| grep xxx |` `\\` バックスラッシュそのもので、何もエスケープしない `c:\\temp, \\${var}` ====== ========================================================== ============================ .. _escape sequence: .. _escape sequences: .. _Forming escape sequences: エスケープシーケンスの記法 '''''''''''''''''''''''''''' バックスラッシュは、テストデータ中で入力するのが難しい文字を扱うときに、文字を表現する特殊なエスケープシーケンスにも使われます。 .. table:: エスケープシーケンス :class: tabular ============= ==================================== ============================ シーケンス 意味 例 ============= ==================================== ============================ `\n` 改行文字 `first line\n2nd line` `\r` 復帰文字 `text\rmore text` `\t` タブ `text\tmore text` `\xhh` 16 進 `hh` で表される文字 `null byte: \x00, ä: \xE4` `\uhhhh` 16 進 `hhhh` で表される文字 `snowman: \u2603` `\Uhhhhhhhh` 16 進 `hhhhhhhh` で表される文字 `love hotel: \U0001f3e9` ============= ==================================== ============================ .. note:: テストデータ中でエスケープシーケンスで表した文字は、 `\x02` のようなものも含め、全て Unicode での表現なので、必要に応じて明示的な変換が必要です。 変換は、例えば、 :ref:`BuiltIn` や :ref:`String` ライブラリの :name:`Convert To Bytes` や :name:`Encode String To Bytes` といったキーワードでできます。 あるいは、Python コードで `str(value)` や `value.encode('UTF-8')` のようにして変換できます。 .. note:: `\x`, `\u`, `\U` に無効な16進の値を指定した場合は、バックスラッシュ抜きの16進値に変換されます。 たとえば、 `\xAX` (16進でない) や `\U00110000` (値が大きすぎる) は、それぞれ `xAX` や `U00110000` になります。 ただし、この挙動は将来変更される可能性があります。 .. note:: OS による改行文字の違い (Windows は `\r\n` , それ以外は `\n` elsewhere) を吸収したい場合は、 :ref:`組み込み変数 ` の `${\n}` を使えます。 .. note:: `\n` の後にエスケープなしの空白文字を続けた場合は無視されます。 つまり、 `two lines\nhere` と `two lines\n here` は同じになります。 これはもともと、 HTML 形式で改行を含む長い行を折り返せるようにするための措置ですが、他のフォーマットにも適用されています。 唯一の例外は、 :ref:`拡張変数記法 ` 中の空白文字は無視されないというルールです。 .. note:: `\x`, `\u`, `\U` のエスケープシーケンスは Robot Framework 2.8.2 で導入されました。 .. _Prevent ignoring empty cells: 空セルを無視させない方法 '''''''''''''''''''''''''''' セルの前後にあるスペースや、セル内の複数連続するスペースは :ref:`無視される ` ので、キーワードの引数などでスペースを無視させたくないときには、スペースをエスケープする必要があります。 空のセルを無視させたくないときと同じように、 :ref:`組み込み変数 ` の `${SPACE}` でも表現できます。 キーワードの引数に空の値を指定したい場合など、データを :ref:`無視 ` させたくないときには、空セルのエスケープが必要です。 行の末尾側にある空のセルは、テストデータをどのフォーマットで書いていてもエスケープが必要です。 :ref:`スペース区切り方式 ` のフォーマットの場合は、空の値はどこにあっても常にエスケープせねばなりません。 空のセルは、バックラッシュでエスケープするか、 :ref:`組み込み変数 ` の `${EMPTY}` で表現します。 見やすさの観点から、基本的に後者を勧めます。 例外は、 :ref:`スペース区切り方式 ` のフォーマットで :ref:`for ループ ` を書いていて、セルのインデントにバックスラッシュを使うときです。 こうしたケースについて、以下に例を挙げます。最初の例は HTML のテーブル、次の例はスペース区切り方式のテキストフォーマットです: .. table:: :class: example ================== ============ ========== ========== =================================== Test Case Action Argument Argument Argument ================== ============ ========== ========== =================================== Using backslash Do Something first arg \\ Using ${EMPTY} Do Something first arg ${EMPTY} Non-trailing empty Do Something second arg # HTML 形式は行末のエスケープ不要 For loop :FOR ${var} IN @{VALUES} \ Log ${var} # エスケープは不要 ================== ============ ========== ========== =================================== .. sourcecode:: robotframework *** Test Cases *** Using backslash Do Something first arg \ Using ${EMPTY} Do Something first arg ${EMPTY} Non-trailing empty Do Something ${EMPTY} second arg # スペース区切り方式ではエスケープが必要 For loop :FOR ${var} IN @{VALUES} \ Log ${var} # エスケープが必要。バックスラッシュが見やすい .. _Prevent ignoring spaces: スペースを無視させない方法 ''''''''''''''''''''''''''''' セルの前後にあるスペースや、セル内の複数連続するスペースは :ref:`無視される ` ので、キーワードの引数などでスペースを無視させたくないときには、スペースをエスケープする必要があります。 空のセルを無視させたくないときと同じように、 :ref:`組み込み変数 ` の `${SPACE}` でも表現できます。 .. table:: スペースをエスケープする方法の例 :class: tabular ================================== =============================== =========================================== バックスラッシュを使う方法 `${SPACE}` を使う方法 備考 ================================== =============================== =========================================== :codesc:`\\ 前のスペース`` `${SPACE}前のスペース` :codesc:`後ろのスペース \\` `後ろのスペース${SPACE}` バックスラッシュはスペースの後ろ :codesc:`\\ \\` `${SPACE}` 爆スラッシュはスペースの前後 :codesc:`セル中の \\ \\ スペース` `セル中の${SPACE * 3}スペース` `拡張変数記法`_ ================================== =============================== =========================================== 上の例のように、 `${SPACE}` を使ったほうが、テストデータはわかりやすく書けます。 特に、 :ref:`拡張変数記法 ` と組み合わせることで、スペースが複数個のときに便利です。 .. _split into several rows: .. _Dividing test data to several rows: テストデータを複数行に分ける ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 一行におさまらないデータがあるばあい、省略符号 (`...`) を使って、前行からの続きを書けます。 キーワードテーブルの場合、省略符号の前には、必ず一つ以上空のセルが必要です。 設定テーブルと変数テーブルについては行頭に省略符号を書けます。 どのテーブルも、省略符号よりも前の空のセルは無視されます。 さらに、設定テーブルの項目のうち、値がひとつしかないもの (主にドキュメント) は、データを複数のカラムに分けて記述できます。 その場合、各セルの値は、テストデータを解析するときにスペースで結合されます。 Robot Framework 2.7 からは、ドキュメントとテストスイートのメタデータを複数行に分けて書くと、 :ref:`改行で結合されます ` 。 以下のサンプルは、上記の規則を実演したものです。 最初の3つのテーブルはでは、テストデータは分割されていません。 その次の3つのテーブルを見れば、複数行に分けることで少ないカラム数でテストデータを表現できることがわかります。 .. table:: テストデータ行を分割せず、一行に収めたテーブルの例 :class: example ============ ======= ======= ======= ======= ======= ======= Setting Value Value Value Value Value Value ============ ======= ======= ======= ======= ======= ======= Default Tags tag-1 tag-2 tag-3 tag-4 tag-5 tag-6 ============ ======= ======= ======= ======= ======= ======= .. table:: :class: example ========== ======= ======= ======= ======= ======= ======= Variable Value Value Value Value Value Value ========== ======= ======= ======= ======= ======= ======= @{LIST} this list has quite many items ========== ======= ======= ======= ======= ======= ======= .. table:: :class: example +-----------+-----------------+---------------+------+-------+------+------+-----+-----+ | Test Case | Action | Argument | Arg | Arg | Arg | Arg | Arg | Arg | +===========+=================+===============+======+=======+======+======+=====+=====+ | Example | [Documentation] | Documentation | | | | | | | | | | for this test | | | | | | | | | | case.\\n This | | | | | | | | | | can get quite | | | | | | | | | | long... | | | | | | | +-----------+-----------------+---------------+------+-------+------+------+-----+-----+ | | [Tags] | t-1 | t-2 | t-3 | t-4 | t-5 | | | +-----------+-----------------+---------------+------+-------+------+------+-----+-----+ | | Do X | one | two | three | four | five | six | | +-----------+-----------------+---------------+------+-------+------+------+-----+-----+ | | ${var} = | Get X | 1 | 2 | 3 | 4 | 5 | 6 | +-----------+-----------------+---------------+------+-------+------+------+-----+-----+ .. table:: テストデータ行を分割して、複数行に収めたテーブルの例 :class: example ============ ======= ======= ======= Setting Value Value Value ============ ======= ======= ======= Default Tags tag-1 tag-2 tag-3 ... tag-4 tag-5 tag-6 ============ ======= ======= ======= .. table:: :class: example ========== ======= ======= ======= Variable Value Value Value ========== ======= ======= ======= @{LIST} this list has ... quite many items ========== ======= ======= ======= .. table:: :class: example =========== ================ ============== ========== ========== Test Case Action Argument Argument Argument =========== ================ ============== ========== ========== Example [Documentation] Documentation for this test case. \ ... This can get quite long... \ [Tags] t-1 t-2 t-3 \ ... t-4 t-5 \ Do X one two three \ ... four five six \ ${var} = Get X 1 2 \ ... 3 4 \ ... 5 6 =========== ================ ============== ========== ==========