Re: [ReSpec] `data-tests` and new goodies in v15+

Firstly, I'd like to apologize to Tab. I took a dig at BikeShed in my last email, and it was unwarranted. Sorry, Tab. 

BikeShed is an amazing tool - and in many ways far superior to ReSpec (e.g., cross references and IDL support is unquestionably superior). If you've not seen BikeShed, please take a look: 
https://github.com/tabatkins/bikeshed

These tools serve different audiences. I'm, however, extremely thankful that BikeShed exists because it drives innovation in ReSpec through friendly competition and the drive to make better specs for the web. 

> On Aug 16, 2017, at 4:24 AM, Tab Atkins Jr. <jackalmage@gmail.com> wrote:
> 
>> On Thu, Jul 27, 2017 at 3:08 AM, Marcos Caceres <mcaceres@mozilla.com> wrote:
>> Hi All
>> 
>> 🎅 new goodies, just for you:
>> 
>> 🎁 Link to your (web-platform-) tests: add `testSuiteURI` + a space
>> separated list of paths to `data-tests` to link to tests. See below.
> 
> Any chance of seeing a live example of this, so I can tell how it
> works and what sort of UI you're producing? Happy to reproduce this in Bikeshed.

Examples are visible in the Payment Request API - for example:

https://w3c.github.io/payment-request/#constructor

Note that I remove the details element before publication, as apparently details can't be a child of  another block-level element so the validator gets upset. I don't know why HTML has this restriction or if there some good reason for it. 

Also, the css doesn't work super great: opening details sometimes causes the box to move, as the width of the container element changes. 

>> 🎁 `isPreview` config option: allows you to denote that a spec is
>> just a preview. This is now used by Tobie's pull request preview tool.
> 
> From reading the PR, it appears that this just adds the warning box?

Correct. Seems sufficient for "PR preview". 

> If so, then for any Bikeshed users, this can be done by adding a
> `Warning: not-ready` metadata to your document, or calling `bikeshed
> spec --md-warning="not ready"` to dynamically add it during
> generation.
> 
>> 🎁 If you have `github`, you don't need "shortName" anymore
>> (shortName is derived from your github repo!)
> 
> Ah, so if my repo is `tabatkins/css-foo`, it'll assume the shortname
> is `css-foo` by default?

Correct. 

> That seems like it would misfire on levelled
> specs, no?

Probably. I don't know of any ReSpec-based specs that use levels. 

>  Or does it have some logic for that?

Not right now for the reason above. Using "shortName:" still lets editors override the derived one. 

> 
>> ## data-tests attribute (beta!)
>> 
>> The `data-tests` attribute takes a list of space-separated URLs,
>> allowing you to link tests to testable assertions. This will add a
>> details drop down to the testable assertion, with an unordered list of
>> tests.
> 
> I recommend changing this to comma-separated, since this is still new.
> If you ever want to associate more data with the url, you'll be very
> sorry about using space separation. I did, in the past. ^_^

Thanks! I've sent a PR to address this. I think only my specs currently link to tests. 

> 
>> The data-test works together with the testSuiteURI config option, so
>> it must be present or ReSpec will yell at you.
>> 
>> It's best used with <p> and <li> elements.
>> 
>> ## Examples of usage
>> ```
>> <script>
>> const respecConfig = {
>> testSuiteURI: "https://wpt.fyi/payment-request/",
>> };
>> </script>
>> 
>> <p data-tests="test-1.html test-2.html">
>>  The user agent MUST do this stuff...
>> </p>
>> ```
> 
> Does this require the element to have an ID or something to link to?

No. But it might be useful for tests and specs to reference back to each other. However, it can be very fragile. 


> I
> probably just need to see it in action to see what this actually does.
> ^_^

As you can see, what it does is super simple. 

> 
> ~TJ