Merge pull request #24 from bldl/testing-section

mathiasness · web-flow · commit 80880945007b · 2024-12-05T12:25:54.000+01:00
Testing section
diff --git a/upsert-tutorial/index.html b/upsert-tutorial/index.html
@@ -1478,59 +1478,69 @@ <h2>Testing with Test262</h2>
                     <div class="content-body">
                         <h3 id="writing-tests-for-test262">Writing tests for <a href="https://github.com/tc39/test262" target="_blank">Test262</a></h3>
                         <p>   When it comes to testing implementations, there are some guidelines to follow.
-                            The official guidelines state that an acceptable test in Test262 is the following:</p>
-                        <pre><code>Any test that exercises observable grammar or semantics, originating with citable,
-ormative text in the latest draft of the ECMAScript® Language Specification,
-the ECMAScript® Internationalization API Specification, the The JSON Data Interchange Syntax,
-a Stage 3 proposal or a Pull Request which makes a normative change to any of those specifications.
-</code></pre>
-                        <p>   The key point for this, is that we can write tests for any observable grammar or semantic from our specification.</p>
-                        <p>   First we need to identify the so-called testable lines in our specification.
-                            One way to think about it, is when the behaviour of the specification is observable to the user, it is testable.</p>
-                        <p>   An example of easily testable line in our specification is:
-                            <code>2. Perform ? RequireInternalSlot(M, [[MapData]])</code></p>
-                        <p>   Recall that this line, among other things, checks if <code>this</code> is an Object, therefore we can test it by trying it on non-objects.
-                            Primitive types in JavaScript™ are not considered objects.
-                            So an example of the tests you can write for this, could look like this:</p>
+                            The <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#acceptable-tests">official guidelines</a> state that an acceptable test in Test262 is the following:</p>
+                        <blockquote>
+                            <p><em>Any test that exercises observable grammar or semantics, originating with citable, normative text in the latest draft of the ECMAScript® Language Specification, the ECMAScript® Internationalization API Specification, the The JSON Data Interchange Syntax, a Stage 3 proposal or a Pull Request which makes a normative change to any of those specifications.</em></p>
+                        </blockquote>
+                        <p>   The key point for this is that we should write tests for any observable grammar or semantic from our specification.</p>
+                        <p>   First, we need to identify the so-called <em>testable lines</em> in our specification.
+                            One way to think about it is this: whenever the behaviour of the specification is observable to the user, then it is testable.</p>
+                        <p>   An example of an easily testable line in our specification is:</p>
+                        <pre><code class="language-lua">2. Perform ? RequireInternalSlot(M, [[MapData]]).
+</code></pre>
+                        <p>   Recall that this line, among other things, checks whether <code>this</code> is an <code>Object</code>. Therefore, we can test it by trying it on non-objects, for example, on <a href="https://262.ecma-international.org/#sec-primitive-value">values of primitive types</a>.
+                            Here is an example of a test where we assert that calling the <code>upsert</code> method on <code>false</code> with arguments <code>1</code> and <code>1</code> will throw  <code>TypeError</code> exception:</p>
                         <pre><code class="language-js">var m = new Map();
 
 assert.throws(TypeError, function () {
     m.upsert.call(false, 1, 1);
 });
 </code></pre>
-                        <p>   The <code>assert</code> is part of the Test262 suite, here we assert that a TypeError is thrown.</p>
-                        <p>   You can find the rest of the functions for assert <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#test-environment" target="_blank">here</a>.</p>
-                        <h3 id="more-than-just-testing">More than just testing</h3>
-                        <p>   Additional to the tests, there is a strict guide for documentation for the test.</p>
-                        <p>   You start the test by declaring the copyright, here you just fill in the year and your name:</p>
+                        <p>   The <code>assert</code> method is a part of the Test262 suite. You can find the rest of the functions for assert <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#test-environment" target="_blank">here</a>.</p>
+                        <h3 id="more-than-just-testing">More Than Just Testing</h3>
+                        <p>   Test262 test should be documented in a <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#test-case-style">certain manner</a>. </p>
+                        <p>   We start with stating the copyright:</p>
                         <pre><code>// Copyright (C) *Year *Name. All rights reserved.
 // This code is governed by the BSD license found in the LICENSE file.
 </code></pre>
-                        <p>   The rest of the information is enclosed in a YAML string and has specified values to simplify parsing.
-                            All the info is inside the YAML tags <code>/*---</code> and <code>---*/</code>.</p>
-                        <p>   We start with the required key <code>esid</code>, which is the ECMAScript® identifier.
-                            This doesn&#39;t apply to us yet, as the proposal hasn&#39;t gotten one, therefore we will use <code>pending</code>.</p>
+                        <p>   The rest of the test meta-information is enclosed in a YAML string and mentions specific fields (&quot;keys), some of which we explain in the table below.
+                            The complete list of possible keys can be found <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#frontmatter" target="_blank">here</a>.</p>
+                        <table class="styled-table">
+                            <thead>
+                            <tr>
+                                <th>field</th>
+                                <th>explanation</th>
+                            </tr>
+                            </thead>
+                            <tbody><tr>
+                                <td><code>esid</code></td>
+                                <td>reference to specification section, e.g. <code>sec-well-known-symbols</code></td>
+                            </tr>
+                            <tr>
+                                <td><code>description</code></td>
+                                <td>short one-line description stating the purpose of the test, e.g., &quot;Throws a TypeError if <code>this</code> is not an object&quot;</td>
+                            </tr>
+                            <tr>
+                                <td><code>info</code></td>
+                                <td>verbose description of the test mentioning, e.g., what does the method look like, which line of code are we testing, etc.</td>
+                            </tr>
+                            </tbody></table>
+                        <p>   For our <code>upsert</code> specification, the required key <code>esid</code> is not applicable yet, as (at the time of writing) the proposal hasn&#39;t gotten one. Therefore, we will use <code>pending</code>.</p>
                         <pre><code>esid: pending
 </code></pre>
-                        <p>   Next comes the description which is the other required key.
-                            The description should be short and on one line regarding the purpose of this testcase.
-                            In our case, it will look something like: </p>
+                        <p>   Next comes the <code>description</code> key. In our case, it will look like this: </p>
                         <pre><code>description: &gt;
      Throws a TypeError if &#39;this&#39; is not an object
 </code></pre>
-                        <p>   Although not required, we should fill out the <code>info</code> key as well.
-                            Some points that are beneficial here are:
-                            - What does the method look like?
-                            - Which line of code are we testing?</p>
+                        <p>   Although not required, we fill out the <code>info</code> key as well:</p>
                         <pre><code>info: |
      Map.upsert( key , value )
 
-     1. Let M be the this value
-     2. Perform ? RequireInternalSlot(M, [[MapData]])
+     1. Let M be the this value.
+     2. Perform ? RequireInternalSlot(M, [[MapData]]).
      ...
 </code></pre>
-                        <p>   There are many other keys we can look at, but if you want to learn more about them, check out this <a href="https://github.com/tc39/test262/blob/main/CONTRIBUTING.md#frontmatter" target="_blank">link.</a></p>
-                        <p>   Our full test should now look something like this:</p>
+                        <p>   Our full test should now look as follows:</p>
                         <pre><code class="language-js">// Copyright (C) 2024 Sune Eriksson Lianes. All rights reserved.
 // This code is governed by the BSD license found in the LICENSE file.
 /*---
@@ -1550,8 +1560,8 @@ <h3 id="more-than-just-testing">More than just testing</h3>
     m.upsert.call(false, 1, 1);
 });
 </code></pre>
-                        <h3 id="fill-in-test-cases">Fill in test cases</h3>
-                        <p>   We can now fill in with other test cases (non-objects):</p>
+                        <h3 id="filling-in-test-cases">Filling in Test Cases</h3>
+                        <p>   We can now fill in other test cases related to calling <code>upsert</code> on non-objects:</p>
                         <pre><code class="language-js">// Copyright (C) 2024 Sune Eriksson Lianes. All rights reserved.
 // This code is governed by the BSD license found in the LICENSE file.
 /*---
@@ -1592,12 +1602,14 @@ <h3 id="fill-in-test-cases">Fill in test cases</h3>
     m.upsert.call(Symbol(), 1, 1);
 });
 </code></pre>
-                        <p>   You can take a look at other tests written in the test262 folder or try to write some tests yourself.</p>
-                        <h3 id="running-tests-in-spidermonkey">Running tests in SpiderMonkey</h3>
-                        <p>   To add the test you simply create the file in <code>mozilla-unified/js/src/tests/test262/built-ins/Map/</code>.
-                            Preferably creating a folder for the proposal as well.</p>
-                        <p>   When this is done, you can run the tests with <code>./mach jstests built-ins/Map</code>, or be even more specific if you have created a folder.</p>
-                        <p>   You will then see something like this, depending on how many tests are run:</p>
+                        <p>   You can take a look at other tests in the <a href="/test262"><code>test262</code></a> folder or try to write some tests yourself.</p>
+                        <h3 id="running-tests-in-spidermonkey">Running Tests in SpiderMonkey</h3>
+                        <p>   To add a test, we create a file with the test in <code>mozilla-unified/js/src/tests/test262/built-ins/Map/</code>.
+                            It makes sense to create a folder for all the tests related to the proposal.</p>
+                        <p>   We can run the tests by executing</p>
+                        <pre><code class="language-sh">./mach jstests built-ins/Map
+</code></pre>
+                        <p>   Depending on how many tests are run, the output of this command will be similar to the following:</p>
                         <pre><code class="language-sh">[1|0|0|0]  12% =====&gt;
 [2|0|0|0]  25% ============&gt;
 [3|0|0|0]  37% ===================&gt;
@@ -1609,7 +1621,7 @@ <h3 id="running-tests-in-spidermonkey">Running tests in SpiderMonkey</h3>
 [8|0|0|0] 100% ======================================================&gt;|
 0.4s
 </code></pre>
-                        <p>   A general tip for testing is looking at how similar lines are tested in other implementations.</p>
+                        <p>   As with the implementation itself, a general tip when writing Test262 tests is to look at how similar lines in other specifications are tested.</p>
 
                     </div>
                 </section>
diff --git a/upsert-tutorial/style.css b/upsert-tutorial/style.css
@@ -122,6 +122,7 @@ pre {
     overflow-x: auto; /* Horizontal scroll for long lines */
     font-family: Consolas, "Courier New", monospace; /* Monospace font */
     font-size: 0.9em; /* Slightly smaller font size for a code look */
+    margin: 10px 10px 15px;
 }
 
 /* Tab Container Styles */
@@ -196,4 +197,43 @@ pre {
     margin: 0 auto 1rem;         
     width: 90%;                  
     max-width: 50rem;           
-}
+}
+
+/* Table styling */
+.styled-table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 25px 0;
+    font-size: 18px;
+    text-align: left;
+    box-shadow: 0 0 20px rgba(0, 0, 0, 0.15);
+}
+
+.styled-table thead tr {
+    background-color: #009879;
+    color: #ffffff;
+    text-align: left;
+    font-weight: bold;
+}
+
+.styled-table th, .styled-table td {
+    padding: 12px 15px;
+    border: 1px solid #dddddd;
+}
+
+.styled-table tbody tr {
+    border-bottom: 1px solid #dddddd;
+}
+
+.styled-table tbody tr:nth-of-type(even) {
+    background-color: #f3f3f3;
+}
+
+.styled-table tbody tr:last-of-type {
+    border-bottom: 2px solid #009879;
+}
+
+.styled-table tbody tr:hover {
+    background-color: #f1f1f1;
+    cursor: pointer;
+}
