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