1CSS parsing tests 2################# 3 4This repository contains implementation-independent test for CSS parsers, 5based on the 2013 draft of the `CSS Syntax Level 3`_ specification. 6 7.. _CSS Syntax Level 3: http://dev.w3.org/csswg/css-syntax-3/ 8 9The upstream repository for these tests is at 10https://github.com/SimonSapin/css-parsing-tests 11 12 13Projects using this 14=================== 15 16CSS parsers using these tests: 17 18* `tinycss2 <https://github.com/SimonSapin/tinycss2>`_ (Python) 19* `rust-cssparser <https://github.com/mozilla-servo/rust-cssparser>`_ 20 (Rust, used in `Servo <https://github.com/mozilla/servo/>`_) 21* `Crass <https://github.com/rgrove/crass/>`_ (Ruby) 22 23 24Importing 25========= 26 27The recommended way to use these tests in an implementation 28is to import them with git-subtree_. 29 30.. _git-subtree: https://github.com/git/git/tree/master/contrib/subtree 31 32To import the first time to a ``./css-parsing-tests`` sub-directory, 33run this from the top-level of a git repository:: 34 35 git subtree add -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master 36 37Later, to merge changes made in the upstream repository, run:: 38 39 git subtree pull -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master 40 41 42Test files 43========== 44 45CSS Syntax specification describes a number of "functions". 46Each ``.json`` file in this repository corresponds to such a function. 47The files are encoded as UTF-8 48and each contain a JSON array with an even number of items, 49where each pair of items is one function input 50associated with the expected result. 51 52``component_value_list.json`` 53 Tests `Parse a list of component values 54 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-component-values>`_. 55 The Unicode input is represented by a JSON string, 56 the output as an array of `component values`_ as described below. 57 58``component_value_list.json`` 59 Tests `Parse a component value 60 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-component-value>`_. 61 The Unicode input is represented by a JSON string, 62 the output as a `component value`_. 63 64``declaration_list.json`` 65 Tests `Parse a list of declarations 66 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-declarations>`_. 67 The Unicode input is represented by a JSON string, 68 the output as an array of declarations_ and at-rules_. 69 70``one_declaration.json`` 71 Tests `Parse a declaration 72 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-declaration>`_. 73 The Unicode input is represented by a JSON string, 74 the output as a declaration_. 75 76``one_rule.json`` 77 Tests `Parse a rule 78 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-rule>`_. 79 The Unicode input is represented by a JSON string, 80 the output as a `qualified rule`_ or at-rule_. 81 82``rule_list.json`` 83 Tests `Parse a list of rules 84 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-rules>`_. 85 The Unicode input is represented by a JSON string, 86 the output as a list of `qualified rules`_ or at-rules_. 87 88``stylesheet.json`` 89 Tests `Parse a stylesheet 90 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_. 91 The Unicode input is represented by a JSON string, 92 the output as a list of `qualified rules`_ or at-rules_. 93 94``stylesheet_bytes.json`` 95 Tests `Parse a stylesheet 96 <http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_ 97 together with `The input byte stream 98 <http://dev.w3.org/csswg/css-syntax/#input-byte-stream>`_. 99 The input is represented as a JSON object containing: 100 101 * A required ``css_bytes``, the input byte string, 102 represented as a JSON string where code points U+0000 to U+00FF 103 represent bytes of the same value. 104 * An optional ``protocol_encoding``, 105 a protocol encoding label as a JSON string, or null. 106 * An optional ``environment_encoding``, 107 an environment encoding label as a JSON string, or null. 108 * An optional ``comment`` that is ignored. 109 110 The output is represented a list of `qualified rules`_ or at-rules_. 111 112``color3.json`` 113 Tests the ``<color>`` syntax `defined in CSS Color Level 3 114 <http://www.w3.org/TR/css3-color/#colorunits>`_. 115 The Unicode input is represented by a JSON string, 116 the output as one of: 117 118 * null if the input is not a valid color in CSS syntax 119 * The string "currentColor" for the currentColor keyword 120 * An array of length 4 for every other values: 121 four (floating point) numbers for the Red, Green, Blue and Alpha channel. 122 Each value is between 0 and 1. 123 124``color3_hsl.json`` 125 Same as ``color3.json``. 126 This file is generated by the ``make_color3_hsl.py`` Python script. 127 128``color3_keywords.json`` 129 Same as ``color3.json``, 130 except that the values for the Red, Green and Blue channel 131 are between 0 and 255. 132 This file is generated by the ``make_color3_keywords.py`` Python script. 133 134``An+B.json`` 135 Tests the `An+B <http://dev.w3.org/csswg/css-syntax/#the-anb-type>`_ 136 syntax defined in CSS Syntax Level 3. 137 This `differs <http://dev.w3.org/csswg/css-syntax/#changes>`_ from the 138 `nth grammar rule <http://www.w3.org/TR/css3-selectors/#nth-child-pseudo>`_ 139 in Selectors Level 3 only in that 140 ``-`` charecters and digits can be escaped in some cases. 141 The Unicode input is represented by a JSON string, 142 the output as null for invalid syntax, 143 or an array of two integers ``[A, B]``. 144 145 146Result representation 147===================== 148 149AST nodes (the results of parsing) are represented in JSON as follow. 150This representation was chosen to be compact 151(and thus less annoying to write by hand) 152while staying unambiguous. 153For example, the difference between ``@import`` and ``\@import`` is not lost: 154they are represented as ``["at-keyword", "import"]`` and ``["ident", "@import"]``, 155respectively. 156 157 158Rules and declarations 159---------------------- 160 161.. _at-rule: 162.. _at-rules: 163.. _qualified rule: 164.. _qualified rules: 165.. _declaration: 166.. _declarations: 167 168 169At-rule 170 An array of length 4: the string ``"at-rule"``, 171 the name (value of the at-keyword) as a string, 172 the prelude as a nested array of `component values`_, 173 and the optional block as a nested array of component value, or null. 174 175Qualified rule 176 An array of length 3: the string ``"qualified rule"``, 177 the prelude as a nested array of `component values`_, 178 and the block as a nested array of component value. 179 180 181Declaration 182 An array of length 4: the string ``"declaration"``, the name as a string, 183 the value as a nested array of `component values`_, 184 and a the important flag as a boolean. 185 186 187.. _component value: 188.. _component values: 189 190Component values 191---------------- 192 193<ident> 194 Array of length 2: the string ``"ident"``, and the value as a string. 195 196<at-keyword> 197 Array of length 2: the string ``"at-keyword"``, and the value as a string. 198 199<hash> 200 Array of length 3: the string ``"hash"``, the value as a string, 201 and the type as the string ``"id"`` or ``"unrestricted"``. 202 203<string> 204 Array of length 2: the string ``"string"``, and the value as a string. 205 206<bad-string> 207 Array of length 1: the string ``"bad-string"``. 208 209<url> 210 Array of length 2: the string ``"url"``, and the value as a string. 211 212<bad-url> 213 Array of length 1: the string ``"bad-url"``. 214 215<delim> 216 The value as a one-character string. 217 218<number> 219 Array of length 4: the string ``"number"``, the representation as a string, 220 the value as a number, and the type as the string ``"integer"`` or ``"number"``. 221 222<percentage> 223 Array of length 4: the string ``"percentage"``, the representation as a string, 224 the value as a number, and the type as the string ``"integer"`` or ``"number"``. 225 226<dimension> 227 Array of length 4: the string ``"dimension"``, the representation as a string, 228 the value as a number, the type as the string ``"integer"`` or ``"number"``, 229 and the unit as a string. 230 231<unicode-range> 232 Array of length 3: the string ``"unicode-range"``, 233 followed by the *start* and *end* integers as two numbers. 234 235<include-match> 236 The string ``"~="``. 237 238<dash-match> 239 The string ``"|="``. 240 241<prefix-match> 242 The string ``"^="``. 243 244<suffix-match> 245 The string ``"$="``. 246 247<substring-match> 248 The string ``"*="``. 249 250<column> 251 The string ``"||"``. 252 253<whitespace> 254 The string ``" "`` (a single space.) 255 256<CDO> 257 The string ``"<!--"``. 258 259<CDC> 260 The string ``"-->"``. 261 262<colon> 263 The string ``":"``. 264 265<semicolon> 266 The string ``";"``. 267 268<comma> 269 The string ``","``. 270 271{} block 272 An array of length N+1: the string ``"{}"`` 273 followed by the N `component values`_ of the block’s content. 274 275[] block 276 An array of length N+1: the string ``"[]"`` 277 followed by the N `component values`_ of the block’s content. 278 279() block 280 An array of length N+1: the string ``"()"`` 281 followed by the N `component values`_ of the block’s content. 282 283Function 284 An array of length N+2: the string ``"function"`` 285 and the name of the function as a string 286 followed by the N `component values`_ of the function’s arguments. 287 288<bad-string> 289 The array of two strings ``["error", "bad-string"]``. 290 291<bad-url> 292 The array of two strings ``["error", "bad-url"]``. 293 294Unmatched <}> 295 The array of two strings ``["error", "}"]``. 296 297Unmatched <]> 298 The array of two strings ``["error", "]"]``. 299 300Unmatched <)> 301 The array of two strings ``["error", ")"]``. 302