A specification is not a user manual

• Written for implementers, not end users
• The only documentation with the latest technology
• Pick random sections from contents list
• Follow all the cross-references

Find The W3C Specifications

http://www.w3.org/TR/

The structure of specifications

• A section that tells how each spec is put together

The structure of specifications

• A section that tells how to read the specification

Key words for use

• MUST, REQUIRED, SHALL
  • absolute requirement
• MUST NOT, SHALL NOT
  • absolute prohibition
• SHOULD, RECOMMENDED
  • can be implemented
  • have a good reason for not doing
• SHOULD NOT
  • have a good reason for doing

Words for the Wise / Learning

• normative this section is normative
• non-normative not testable sections
• user agent
• RFC this is considered "normative language"
• IDL interface definition language

Sample

Product

Strictness level

Prerequisites

Behaviour

Defined Terms

Mapping to code

User agents must not allow the user to set the value to a non-empty string that is not a valid date string.

                      
<input id="invalid" type="date" value="invalid_value">
<script>
  console.log(document.querySelector("#invalid").value == "");
</script>
                      
                      

Language issue?

• English: HTML5 form element
• Chinese: HTML5 form 元素
• W3C 文档规范术语表 by HTML5 中文小组

HTML5 中文兴趣小组

宗旨：以中文（简体或繁体）协调及讨论 HTML5 规范以及 HTML5 相关的规范，收集这些规范的评论与问题，以及在这些规范中文环境下的特殊测试案例。

加入：寄一封标题为「subscribe」的信至 public-html-ig-zh-request@w3.org

testharness

testharness.js and testharnessreport.js

							
<script src="/resources/testharness.js"></script>
<script src="/resources/testharnessreport.js"></script>
							
						

• A framework to simplify and standardize JS test creation
• In the resources directory as subrepo in both the CSS and WPT test repos

• JavaScript API for making common test assertions
• Should be used by all JavaScript tests
• Path must be to /resources directory at root level
  • Locally, copy the resources directory to the root of your drive
  • Or simply create a symlink from /resources sudo ln -s [path/to/resources/dir] /resources
• Element with id="log" should exist in test file
  • Test results table will be added to this element, if it exists

The test() function

							
test(test_function, name, properties)
							
						

• Used for synchronous tests
  • async_test() is also defined by testharness.js for asychronous testing
• Documented and implemented in testharness.js
• Used to define an individual test case in a file
  • Common for a file to have multiple calls to test()
• testharness.js will display PASS/FAIL for each call to test()

test() Argument 1: test_function

							
test(test_function, name, properties)
							
						

• test_function must be an object, not a function call
• test_function should be testharness assert method
  • Can also be user defined if no assert method provides the needed functionality
• Result from the assertion will determine PASS/FAIL
• Usage example:

								  
test(function() { assert_true(true) }, name, properties)
								  
							  

test() Argument 2: Name

							  
		test(test_function, name, properties)
							  
						  

• name is a string that identifies the test
• name should be short, unique, and must not change
• name will be displayed in the test results table
• Usage example:

								  
test(function() { assert_true(true) }, "test_name", properties)
								  
							  

test() Argument 3: Properties

							  
		test(test_function, name, properties)
							  
						  

• properties is an object that overrides defaults
• properties is an optional argument
• Recognized properties include timeout and metadata
• Usage example:

								  
test(function() { assert_true(true) }, 
  "test_name", 
  { timeout:1000, assert: 'This should always be true.' }
)
								  
							  

Assert methods

• testharness.js provides a number of assert methods
  • Full list is provided in the comment section of testharness.js
  • Typically used in the test_function for test()
• All assert methods contain an optional description argument that is only output if the assertion fails
  • Used to provide additional debug information
• All asserts must be located in a call to test()
  • asserts outside won't be detected correctly by the harness and may cause a file to stop testing

Assert Example

							  
assert_equals(actual, expected, description)
							  
						  

• actual: The actual value from the functionality being tested
• expected: The expected value
• description (optional): Output only if the assertion fails
• Usage example:

							  
assert_equals(getData("myElement"), 100, "Expected value for myElement is 100")
							  
						  

METADATA

                        
<!DOCTYPE html>
<meta charset='utf-8'>
<title>[Test Area]: [Title/Scope of Test]</title>
<link rel="author" title="[Name of Author]" href="mailto: or http://..">
<link rel="help" href="http://www.w3.org/TR/[link to tested section]">
                        
                      

METADATA

                        
...
<script src="/resources/testharness.js"></script>
<script src="/resources/testharnessreport.js"></script>
                        
                      

• testharness.js and testharnessreport.js imported
• Path to both scripts points at /resources directory at root level

BODY

<div id="myDiv" style="display: none">
  <input id="invalid_value" type="date" value="invalid-date">
</div>
<div id="log"></div>

<script>
    test(function() {
        assert_equals(document.getElementById("invalid_value").value, "");
    },
    "User agents must not allow the user to set the value to"
    + " a non-empty string that is not a valid date string.");
</script>
                        
                      

• myDiv div used as test element - translate applied in JS
• log div used as container for test results
• test() uses assert_equals as test_function
• assert_equals actual argument supplied by API call

Completed File

						   <!DOCTYPE html>
<meta charset='utf-8'>
<title>HTML Test: Forms date state</title>
<link rel="author" title="your name" href="mailto: yourmail@address.com">
<link rel="help" href="http://www.w3.org/html/wg/drafts/html/CR/forms.html#date-state-(type=date)">
<script src="/resources/testharness.js"></script>
<script src="/resources/testharnessreport.js"></script>
<div id="myDiv" style="display: none">
  <input id="invalid_value" type="date" value="invalid-date">
</div>
<div id="log"></div>
<script>
    test(function() {
        assert_equals(document.getElementById("invalid_value").value, "");
    },
    "User agents must not allow the user to set the value to"
    + " a non-empty string that is not a valid date string.");
</script>
					   

Small gift

Q: Which of the path to the testharness scripts is expected?

• A. <script src="resources/testharness.js"></script>
• B. <script src="/resources/testharness.js"></script>
• C. <script src="../resources/testharness.js"></script>
• D. <script src="../../resources/testharness.js"></script>

Small gift

Q: Which of the path to the testharness scripts is expected?

• A. <script src="resources/testharness.js"></script>
• B. <script src="/resources/testharness.js"></script>
• C. <script src="../resources/testharness.js"></script>
• D. <script src="../../resources/testharness.js"></script>