src/third_party/webgl/src/sdk/tests/test-guidelines.md

   1 Contributing WebGL conformance tests Guidelines
   2 ===============================================
   3
   4 Thank you for contributing to the WebGL conformance tests.
   5 Please try to follow these guidelines when submitting a test.
   6
   7 *   If you're new to git [here's a terse set of instructions](http://www.khronos.org/webgl/wiki/Using_Github_To_Contribute "Using Github to Contribute").
   8
   9 *   All changes and/or new tests should go in the sdk/tests/conformance folder
  10
  11 The tests under conformance-suites are snapshots and are only to be updated by
  12 the WebGL Working Group when "official" snapshots are taken.
  13
  14 *   Please use the Khronos Group License (MIT)
  15
  16 These lines appears at the top of every html and js file under sdk/tests/conformance
  17
  18     <!--
  19     /*
  20     ** Copyright (c) 2014 The Khronos Group Inc.
  21     **
  22     ** Permission is hereby granted, free of charge, to any person obtaining a
  23     ** copy of this software and/or associated documentation files (the
  24     ** "Materials"), to deal in the Materials without restriction, including
  25     ** without limitation the rights to use, copy, modify, merge, publish,
  26     ** distribute, sublicense, and/or sell copies of the Materials, and to
  27     ** permit persons to whom the Materials are furnished to do so, subject to
  28     ** the following conditions:
  29     **
  30     ** The above copyright notice and this permission notice shall be included
  31     ** in all copies or substantial portions of the Materials.
  32     **
  33     ** THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  34     ** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  35     ** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  36     ** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  37     ** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  38     ** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  39     ** MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
  40     */
  41     -->
  42
  43 *   Please use code similar to the code in existing tests
  44
  45     Ideally, copy an existing test and modify it for your new test. Try not to duplicate
  46     code that already exists where appropriate. In particular
  47
  48     *   use the functions in WebGLTestUtils rather than duplicating functionality.
  49
  50         In particular, as much as possible, keep the WebGL code in your test specific
  51         to the issue being tested and try to use the helper functions to handle
  52         common setup.
  53
  54         Examples:
  55
  56         *    to create a WebGL context call `WebGLTestUtils.create3DContext`. Passed nothing
  57              it will create an offscreen canvas. Passed a canvas element it will create
  58              a context on that element. Passed a string it will look up the canvas element
  59              with the matching id and create a context from that element.
  60
  61         *    use `WebGLTestUtils.checkCanvas` or `WebGLTestUtils.checkCanvasRect` rather
  62              than checking rendering results by hand.
  63
  64         *    use the various quad and draw functions
  65
  66              *    `WebGLTestUtils.setupUnitQuad` and `WebGLTestUtils.clearAndDrawUnitQuad` for
  67                    simple drawing.
  68
  69              *    `WebGLTestUtils.setupColorQuad`, `WebGLTestUtils.drawFloatColorQuad`, and
  70                   `WebGLTestUilts.drawUByteColorQuad` for drawing in a particular color.
  71
  72              *    `WebGLTestUtils.setupIndexedQuad` and `WebGLTestUtils.clearAndDrawIndexedQuad`
  73                   if you need a higher subdivision of vertices and/or vertex colors.
  74
  75              *    use `WebgLTestUtils.setupTexturedQuad` if you need a unit quad with texture coords.
  76                   By default the positions will be at location 0 and the texture coords at location 1.
  77
  78         *    If you need a custom shader use `WebGLTestUtils.setupProgram`. Note that it takes
  79              the following arguments. `gl`, `shaders`, `opt_attribs`, `opt_locations` where:
  80
  81              `gl` is the WebGL context.
  82
  83              `shaders` are an array of either script element ids, shader source, or WebGLShader
  84              objects. The first element in the array is the vertex shader, the second the fragment
  85              shader.
  86
  87              `opt_attribs` is an optional array of attribute names. If provided the named attributes
  88              will have their locations bound to their index in this array.
  89
  90              `opt_locations` is an optional array of attribute locations. If provided each attribute
  91              name in `opt_attribs` is bound to the corresponding location in `opt_locations`.
  92
  93         *    If you need to wait for a composite call `WebGLTestUtils.waitForComposite`.
  94              As compositing is a browser specific thing this provides a central place to
  95              update all tests that rely on compositing to function.
  96
  97     *   Code/Tag Order
  98
  99         Most tests run inline. They don't use window.onload or the load event. This works by placing
 100         the script tag inside the body, *after* the canvas and required divs.
 101
 102             <canvas id="example"></canvas>
 103             <div id="description"></div>
 104             <div id="console"></div>
 105             <script>
 106             var wtu = WebGLDebugUtils;
 107             var gl = wtu.create3DContext("example");
 108             ...
 109
 110     *   Ending Tests
 111
 112         *   Tests that are short and run synchronously end with
 113
 114                 <script src="../../resources/js-test-post.js"></script>
 115
 116         *   Tests that take a long time use setTimeout so as not to freeze the browser.
 117
 118             Many browsers will terminate JavaScript that takes more than a few seconds to execute
 119             without returning control to the browser. The workaround is code like this
 120
 121                 var numTests = 10;
 122                 var currenTest = 0;
 123                 function runNextTest() {
 124                   if (currentTest == numTests) {
 125                     finishTest();  // Tells the harness you're done.
 126                     return;
 127                   }
 128                   // Run your test.
 129                   ...
 130                   ++currentTest;
 131                   setTimeout(runNextTest, 100);
 132                 }
 133                 runNextTest();
 134
 135             Remember the tests need to run without timing out even and slow mobile devices.
 136             The harness resets the timeout timer every time a test reports success or failure
 137             so as long as some part of your test calls `testPassed` or `testFailed` or one of the
 138             many wrappers (`shouldXXX`, `glErrorShouldBe`, `WebGLTestUtils.checkCanvasXXX`, etc..)
 139             every so often the harness will not timeout your test.
 140
 141         *   The test harness requires the global variable `successfullyParse` to be set to true.
 142             This usually appears at the end of a file.
 143
 144                 var successfullyParsed = true;
 145
 146     *   Do not use browser specific code.
 147
 148         *   Do not check the browser version. Use feature detection.
 149
 150         *   If you do need feature detection consider putting it into WebGLTestUtils so that
 151             other tests can go through the same abstraction and the workaround is isolated
 152             to one place.
 153
 154         *   Vendors may place test harness specific code in the testing infrastructure.
 155
 156                 resources/js-test-pre.js
 157                 conformance/more/unit.js
 158
 159     *   Indent with spaces not tabs. (not everyone uses your tab settings).
 160
 161     *   All HTML files must have a `<!DOCTYPE html>`
 162
 163     *   All HTML files must have a `<meta charset="utf-8">`
 164
 165     *   All JavaScript must start with "use strict";
 166
 167 *   If adding a new test edit the appropriate 00_test_list.txt file
 168
 169     Each folder has a 00_test_list.txt file that lists the test in that folder.
 170     Each new test should be prefixed with the option `--min-version <version>` where
 171     version is 1 more than the newest official version. At the time of this writing
 172     all new tests should be prefixed with `--min-version 1.0.2`
 173
 174