third_party/WebKit/LayoutTests/css-parser/resources/css-parsing-tests/README.rst

CSS parsing tests
#################

This repository contains implementation-independent test for CSS parsers,
based on the 2013 draft of the `CSS Syntax Level 3`_ specification.

.. _CSS Syntax Level 3: http://dev.w3.org/csswg/css-syntax-3/

The upstream repository for these tests is at
https://github.com/SimonSapin/css-parsing-tests


Projects using this
===================

CSS parsers using these tests:

* `tinycss2 <https://github.com/SimonSapin/tinycss2>`_ (Python)
* `rust-cssparser <https://github.com/mozilla-servo/rust-cssparser>`_
  (Rust, used in `Servo <https://github.com/mozilla/servo/>`_)
* `Crass <https://github.com/rgrove/crass/>`_ (Ruby)


Importing
=========

The recommended way to use these tests in an implementation
is to import them with git-subtree_.

.. _git-subtree: https://github.com/git/git/tree/master/contrib/subtree

To import the first time to a ``./css-parsing-tests`` sub-directory,
run this from the top-level of a git repository::

    git subtree add -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master

Later, to merge changes made in the upstream repository, run::

    git subtree pull -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master


Test files
==========

CSS Syntax specification describes a number of "functions".
Each ``.json`` file in this repository corresponds to such a function.
The files are encoded as UTF-8
and each contain a JSON array with an even number of items,
where each pair of items is one function input
associated with the expected result.

``component_value_list.json``
    Tests `Parse a list of component values
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-component-values>`_.
    The Unicode input is represented by a JSON string,
    the output as an array of `component values`_ as described below.

``component_value_list.json``
    Tests `Parse a component value
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-component-value>`_.
    The Unicode input is represented by a JSON string,
    the output as a `component value`_.

``declaration_list.json``
    Tests `Parse a list of declarations
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-declarations>`_.
    The Unicode input is represented by a JSON string,
    the output as an array of declarations_ and at-rules_.

``one_declaration.json``
    Tests `Parse a declaration
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-declaration>`_.
    The Unicode input is represented by a JSON string,
    the output as a declaration_.

``one_rule.json``
    Tests `Parse a rule
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-rule>`_.
    The Unicode input is represented by a JSON string,
    the output as a `qualified rule`_ or at-rule_.

``rule_list.json``
    Tests `Parse a list of rules
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-rules>`_.
    The Unicode input is represented by a JSON string,
    the output as a list of `qualified rules`_ or at-rules_.

``stylesheet.json``
    Tests `Parse a stylesheet
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_.
    The Unicode input is represented by a JSON string,
    the output as a list of `qualified rules`_ or at-rules_.

``stylesheet_bytes.json``
    Tests `Parse a stylesheet
    <http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_
    together with `The input byte stream
    <http://dev.w3.org/csswg/css-syntax/#input-byte-stream>`_.
    The input is represented as a JSON object containing:

    * A required ``css_bytes``, the input byte string,
      represented as a JSON string where code points U+0000 to U+00FF
      represent bytes of the same value.
    * An optional ``protocol_encoding``,
      a protocol encoding label as a JSON string, or null.
    * An optional ``environment_encoding``,
      an environment encoding label as a JSON string, or null.
    * An optional ``comment`` that is ignored.

    The output is represented a list of `qualified rules`_ or at-rules_.

``color3.json``
    Tests the ``<color>`` syntax `defined in CSS Color Level 3
    <http://www.w3.org/TR/css3-color/#colorunits>`_.
    The Unicode input is represented by a JSON string,
    the output as one of:

    * null if the input is not a valid color in CSS syntax
    * The string "currentColor" for the currentColor keyword
    * An array of length 4 for every other values:
      four (floating point) numbers for the Red, Green, Blue and Alpha channel.
      Each value is between 0 and 1.

``color3_hsl.json``
    Same as ``color3.json``.
    This file is generated by the ``make_color3_hsl.py`` Python script.

``color3_keywords.json``
    Same as ``color3.json``,
    except that the values for the Red, Green and Blue channel
    are between 0 and 255.
    This file is generated by the ``make_color3_keywords.py`` Python script.

``An+B.json``
    Tests the `An+B <http://dev.w3.org/csswg/css-syntax/#the-anb-type>`_
    syntax defined in CSS Syntax Level 3.
    This `differs <http://dev.w3.org/csswg/css-syntax/#changes>`_ from the
    `nth grammar rule <http://www.w3.org/TR/css3-selectors/#nth-child-pseudo>`_
    in Selectors Level 3 only in that
    ``-`` charecters and digits can be escaped in some cases.
    The Unicode input is represented by a JSON string,
    the output as null for invalid syntax,
    or an array of two integers ``[A, B]``.


Result representation
=====================

AST nodes (the results of parsing) are represented in JSON as follow.
This representation was chosen to be compact
(and thus less annoying to write by hand)
while staying unambiguous.
For example, the difference between ``@import`` and ``\@import`` is not lost:
they are represented as ``["at-keyword", "import"]`` and ``["ident", "@import"]``,
respectively.


Rules and declarations
----------------------

.. _at-rule:
.. _at-rules:
.. _qualified rule:
.. _qualified rules:
.. _declaration:
.. _declarations:


At-rule
    An array of length 4: the string ``"at-rule"``,
    the name (value of the at-keyword) as a string,
    the prelude as a nested array of `component values`_,
    and the optional block as a nested array of component value, or null.

Qualified rule
    An array of length 3: the string ``"qualified rule"``,
    the prelude as a nested array of `component values`_,
    and the block as a nested array of component value.


Declaration
    An array of length 4: the string ``"declaration"``, the name as a string,
    the value as a nested array of `component values`_,
    and a the important flag as a boolean.


.. _component value:
.. _component values:

Component values
----------------

<ident>
    Array of length 2: the string ``"ident"``, and the value as a string.

<at-keyword>
    Array of length 2: the string ``"at-keyword"``, and the value as a string.

<hash>
    Array of length 3: the string ``"hash"``, the value as a string,
    and the type as the string ``"id"`` or ``"unrestricted"``.

<string>
    Array of length 2: the string ``"string"``, and the value as a string.

<bad-string>
    Array of length 1: the string ``"bad-string"``.

<url>
    Array of length 2: the string ``"url"``, and the value as a string.

<bad-url>
    Array of length 1: the string ``"bad-url"``.

<delim>
    The value as a one-character string.

<number>
    Array of length 4: the string ``"number"``, the representation as a string,
    the value as a number, and the type as the string ``"integer"`` or ``"number"``.

<percentage>
    Array of length 4: the string ``"percentage"``, the representation as a string,
    the value as a number, and the type as the string ``"integer"`` or ``"number"``.

<dimension>
    Array of length 4: the string ``"dimension"``, the representation as a string,
    the value as a number, the type as the string ``"integer"`` or ``"number"``,
    and the unit as a string.

<unicode-range>
    Array of length 3: the string ``"unicode-range"``,
    followed by the *start* and *end* integers as two numbers.

<include-match>
    The string ``"~="``.

<dash-match>
    The string ``"|="``.

<prefix-match>
    The string ``"^="``.

<suffix-match>
    The string ``"$="``.

<substring-match>
    The string ``"*="``.

<column>
    The string ``"||"``.

<whitespace>
    The string ``" "`` (a single space.)

<CDO>
    The string ``"<!--"``.

<CDC>
    The string ``"-->"``.

<colon>
    The string ``":"``.

<semicolon>
    The string ``";"``.

<comma>
    The string ``","``.

{} block
    An array of length N+1: the string ``"{}"``
    followed by the N `component values`_ of the block’s content.

[] block
    An array of length N+1: the string ``"[]"``
    followed by the N `component values`_ of the block’s content.

() block
    An array of length N+1: the string ``"()"``
    followed by the N `component values`_ of the block’s content.

Function
    An array of length N+2: the string ``"function"``
    and the name of the function as a string
    followed by the N `component values`_ of the function’s arguments.

<bad-string>
    The array of two strings ``["error", "bad-string"]``.

<bad-url>
    The array of two strings ``["error", "bad-url"]``.

Unmatched <}>
    The array of two strings ``["error", "}"]``.

Unmatched <]>
    The array of two strings ``["error", "]"]``.

Unmatched <)>
    The array of two strings ``["error", ")"]``.