This spec is not yet ready for implementation.
It exists in this repository to record the ideas and promote discussion.
Before attempting to implement this spec,
please contact the editors.
To the extent possible under law, the editors have waived all copyright
and related or neighboring rights to this work.
In addition, as of 7 August 2016,
the editors have made this specification available under the Open Web Foundation Agreement Version 1.0,
which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.
Abstract
This specification defines the @should rule, which allows an author to define tests of semantics of the custom classnames vocabulary for documentation and testing.
1. Introduction
The growth of a CSS code base and the consequent growth of custom vocabulary
with defined semantics and other relationships brings extended demands to
authors. The @should rule makes these relationships explicit, the
information provided can be used as a base for documentation or as on input for
automatic testing tools.
2. The Syntax Proposal
To define a @should test, you choose an <axis> and its parameter.
It’s syntax is:
The @should rule is only valid inside of a style rule.
Using it outside of a style rule, or inside any other rule,
is invalid and causes the @should to be ignored.
@keyframes foo {from {color: red;}to {color: blue;}@should match ".boo";}
CSS style sheets are generally case-insensitive,
and this is also the case for <axis>.
In addition to conforming to the syntax, axis and parameter need to use axis
type and param format according to their respective specification in order to
be considered conforming.
Only the first should rule is conforming in the example below because
the "example" axis does not exist.
@should match ".boo";@should example "foo";
Canonical name for an axis must be <ident-token>. If multiple tokens are
present in the rule, canonical name is constructed by concatenating all tokens
with hyphens.
The following two examples are equal.
@should not match ".boo";@should not-match ".boo";
3. Axes
An axis defines a rule relative to the current component. It resembles a
function as it takes a current component and provided string as parameters,
and returns a boolean value meaning if the rule was met or not.
An alternative name for an axis is a verb.
Define other axes after a discussion.
3.1. Match
A rule is met if on every element of the current component,
function Element.matches() defined in [dom] with supplied string as its
parameter returns true.
Expand and explain into more detail. Provide Examples.
3.2. Not-match
This axis returns a negation of the match rule with same parameter.
3.3. Appear
Checks that there exists at least one element of the current component
on the page.
Should number of occurrences be allowed to be specified?
3.4. Not-appear
This axis returns true if there is no element of the current component.
Conformance
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
in the normative parts of this document
are to be interpreted as described in RFC 2119.
However, for readability,
these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative
except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with class="example", like this:
This is an example of an informative example.
Informative notes begin with the word “Note”
and are set apart from the normative text with class="note", like this:
