Skip to content

Commit

Permalink
Add testing guideline for naming test files and adding comments
Browse files Browse the repository at this point in the history
  • Loading branch information
soareschen committed Nov 9, 2017
1 parent 16c4e03 commit d19be18
Showing 1 changed file with 37 additions and 0 deletions.
37 changes: 37 additions & 0 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,40 @@ https://wpt.fyi/webrtc/RTCCertificate.html

Thorough example that tests the difference between undefined and null in dictionaries.
https://wpt.fyi/webrtc/RTCDataChannelEvent-constructor.html

## Naming Guidelines

Update to WebIDL definitions in the spec must also update the IDL test file at [/interfaces/webrtc-pc.idl](https://github.com/w3c/web-platform-tests/blob/master/interfaces/webrtc-pc.idl).
A [helper script](http://web-platform-tests.org/writing-tests/idlharness.html)
can be pasted in the console to generate IDL code from the spec HTML. Note that
partial dictionary definition is not supported in idlharness.js, so some manual
editing is required to merge them as one dictionary definition.

In general, a test case written for a class _RTCClass_ on a method _rtcMethod_
should be added to a file named _RTCClass_-_rtcMethod\[-custom-postfix\]_\[.https].html.
The `.https` extension is _required_ for tests calling `getUserMedia()`.

When a test file contain too many test cases, they may be split into multiple
files with different postfixes, e.g. RTCPeerConnection-setLocalDescription-offer.html

Sometimes the test files are named based on the argument dictionary name and the
tested field, e.g. RTCConfiguration-iceServers.html.

A helper JavaScript file may be added to share helper functions across multiple
test files. Helper functions are exposed as global variables and included as
script tags inside test files. (We may consider using ES modules instead if it
become widely available for WPT) Helper files should have as little dependency
to other helper files, as script tags are not good for dependency management.

## Comments

The current tests have detailed comments referencing sections of the spec that
is being tested. New tests may be written with minimal or no comments up to the
author's preference. If a test case is testing specific steps in a spec, it is
recommended to leave at least one line of comment referencing the spec to help
readers quickly understand the objective of the test.

An issue with having too detailed reference comment is they may get outdated when
there is update to the spec. When submitting test PR to update an existing test
file, the author is free to ignore the references, update the references, or
remove them altogether.

0 comments on commit d19be18

Please sign in to comment.