dom/canvas/test/webgl-conf/checkout/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 folder:
  10   *   Tests that apply to WebGL 1 to sdk/tests/conformance
  11   *   Tests that only concern WebGL 2 to sdk/tests/conformance2
  12
  13 The tests under conformance-suites are snapshots and are only to be updated by
  14 the WebGL Working Group when "official" snapshots are taken.
  15
  16 *   Please use the Khronos Group License (MIT)
  17
  18 These lines must appear in a comment at the top of every code file under sdk/tests/conformance
  19
  20 ```
  21 Copyright (c) 2023 The Khronos Group Inc.
  22 Use of this source code is governed by an MIT-style license that can be
  23 found in the LICENSE.txt file.
  24 ```
  25
  26 *   Please use code similar to the code in existing tests
  27
  28     Ideally, copy an existing test and modify it for your new test. Try not to duplicate
  29     code that already exists where appropriate. In particular
  30
  31     *   use the functions in WebGLTestUtils rather than duplicating functionality.
  32
  33         In particular, as much as possible, keep the WebGL code in your test specific
  34         to the issue being tested and try to use the helper functions to handle
  35         common setup.
  36
  37         Examples:
  38
  39         *    to create a WebGL context call `WebGLTestUtils.create3DContext`. Passed nothing
  40              it will create an offscreen canvas. Passed a canvas element it will create
  41              a context on that element. Passed a string it will look up the canvas element
  42              with the matching id and create a context from that element.
  43
  44         *    use `WebGLTestUtils.checkCanvas` or `WebGLTestUtils.checkCanvasRect` rather
  45              than checking rendering results by hand.
  46
  47         *    use the various quad and draw functions
  48
  49              *    `WebGLTestUtils.setupUnitQuad` and `WebGLTestUtils.clearAndDrawUnitQuad` for
  50                    simple drawing.
  51
  52              *    `WebGLTestUtils.setupColorQuad`, `WebGLTestUtils.drawFloatColorQuad`, and
  53                   `WebGLTestUilts.drawUByteColorQuad` for drawing in a particular color.
  54
  55              *    `WebGLTestUtils.setupIndexedQuad` and `WebGLTestUtils.clearAndDrawIndexedQuad`
  56                   if you need a higher subdivision of vertices and/or vertex colors.
  57
  58              *    use `WebgLTestUtils.setupTexturedQuad` if you need a unit quad with texture coords.
  59                   By default the positions will be at location 0 and the texture coords at location 1.
  60
  61         *    If you need a custom shader use `WebGLTestUtils.setupProgram`. Note that it takes
  62              the following arguments. `gl`, `shaders`, `opt_attribs`, `opt_locations`, and
  63              `opt_logShaders` where:
  64
  65              `gl` is the WebGL context.
  66
  67              `shaders` are an array of either script element ids, shader source, or WebGLShader
  68              objects. The first element in the array is the vertex shader, the second the fragment
  69              shader.
  70
  71              `opt_attribs` is an optional array of attribute names. If provided the named attributes
  72              will have their locations bound to their index in this array.
  73
  74              `opt_locations` is an optional array of attribute locations. If provided each attribute
  75              name in `opt_attribs` is bound to the corresponding location in `opt_locations`.
  76
  77              `opt_logShaders` is an optional boolean value. If set to true, the shader source will
  78              be logged on the test page. It is recommended to use this in tests that concentrate on
  79              shaders.
  80
  81         *    If you need to wait for a composite call `WebGLTestUtils.waitForComposite`.
  82              As compositing is a browser specific thing this provides a central place to
  83              update all tests that rely on compositing to function.
  84
  85             *   If you don't care about composition, `wtu.dispatchPromise` makes it easy to
  86                 yield back to the event loop.
  87
  88     *   Code/Tag Order
  89
  90         Most tests run inline. They don't use window.onload or the load event. This works by placing
  91         the script tag inside the body, *after* the canvas and required divs.
  92
  93             <canvas id="example"></canvas>
  94             <div id="description"></div>
  95             <div id="console"></div>
  96             <script>
  97             var wtu = WebGLDebugUtils;
  98             var gl = wtu.create3DContext("example");
  99             ...
 100
 101     *   Ending Tests
 102
 103         *   Tests that are short and run synchronously end with
 104
 105                 <script src="../../js/js-test-post.js"></script>
 106
 107         *   Tests that take a long time use setTimeout so as not to freeze the browser.
 108
 109             Many browsers will terminate JavaScript that takes more than a few seconds to execute
 110             without returning control to the browser. The workaround is code like this
 111
 112                 var numTests = 10;
 113                 var currenTest = 0;
 114                 function runNextTest() {
 115                   if (currentTest == numTests) {
 116                     finishTest();  // Tells the harness you're done.
 117                     return;
 118                   }
 119                   // Run your test.
 120                   ...
 121                   ++currentTest;
 122                   setTimeout(runNextTest, 100);
 123                 }
 124                 runNextTest();
 125
 126             Remember the tests need to run without timing out even and slow mobile devices.
 127             The harness resets the timeout timer every time a test reports success or failure
 128             so as long as some part of your test calls `testPassed` or `testFailed` or one of the
 129             many wrappers (`shouldXXX`, `glErrorShouldBe`, `WebGLTestUtils.checkCanvasXXX`, etc..)
 130             every so often the harness will not timeout your test.
 131
 132         *   The test harness requires the global variable `successfullyParsed` to be set to true.
 133             This usually appears at the end of a file.
 134
 135                 var successfullyParsed = true;
 136
 137     *   Do not use browser specific code.
 138
 139         *   Do not check the browser version. Use feature detection.
 140
 141         *   If you do need feature detection consider putting it into WebGLTestUtils so that
 142             other tests can go through the same abstraction and the workaround is isolated
 143             to one place.
 144
 145         *   Vendors may place test harness specific code in the testing infrastructure.
 146
 147                 js/js-test-pre.js
 148                 conformance/more/unit.js
 149
 150     *   Indent with spaces not tabs. (not everyone uses your tab settings).
 151
 152     *   All HTML files must have a `<!DOCTYPE html>`
 153
 154     *   All HTML files must have a `<meta charset="utf-8">`
 155
 156     *   All JavaScript must start with "use strict";
 157
 158 *   If adding a new test edit the appropriate 00_test_list.txt file
 159
 160     Each folder has a 00_test_list.txt file that lists the test in that folder.
 161     Each new test should be prefixed with the option `--min-version <version>` where
 162     version is 1 more than the newest official version. At the time of this writing
 163     all new tests should be prefixed with `--min-version 1.0.4` or `--min-version 2.0.1`.
 164
 165