netwerk/docs/network_test_guidelines.md

   1 # Networking Test Guidelines
   2
   3 This is a high level document to introduce the different test types that are used in necko. The target audience is newcomer of necko team.
   4
   5 ## Necko Test Types
   6
   7 We only introduce tests under [netwerk/test](https://searchfox.org/mozilla-central/source/netwerk/test) folder in this section.
   8
   9 - [Chrome Tests](https://firefox-source-docs.mozilla.org/testing/chrome-tests/index.html)
  10   - We usually write chrome tests when the code to be tested needs a browser windows to load some particular resources.
  11   - Path: [netwerk/test/browser](https://searchfox.org/mozilla-central/source/netwerk/test/browser)
  12 - [Reftest](https://firefox-source-docs.mozilla.org/testing/webrender/index.html)
  13   - Rarely used in necko.
  14 - [Mochitest](https://firefox-source-docs.mozilla.org/testing/mochitest-plain/index.html)
  15   - Used when the code to be tested can be triggered by WebIDL. e.g., WebSocket and XMLHttpRequest.
  16   - Path: [netwerk/test/mochitests](https://searchfox.org/mozilla-central/source/netwerk/test/mochitests)
  17 - [XPCShell tests](https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html#xpcshell-tests)
  18   - Mostly used in necko to test objects that can be accessed by JS. e.g., `nsIHttpChannel`.
  19   - Path: [netwerk/test/unit](https://searchfox.org/mozilla-central/source/netwerk/test/unit)
  20 - [GTest](https://firefox-source-docs.mozilla.org/gtest/index.html)
  21   - Useful when the code doesn't need a http server.
  22   - Useful when writing code regarding to parsing strings. e.g., [Parsing Server Timing Header](https://searchfox.org/mozilla-central/rev/0249c123e74640ed91edeabba00649ef4d929372/netwerk/test/gtest/TestServerTimingHeader.cpp)
  23 - [Performance tests](https://firefox-source-docs.mozilla.org/testing/perfdocs/index.html)
  24   - Current tests in [netwerk/test/perf](https://searchfox.org/mozilla-central/source/netwerk/test/perf) are all for testing `HTTP/3` code.
  25
  26 There are also [web-platform-tests](https://firefox-source-docs.mozilla.org/web-platform/index.html) that is related to necko. We don't usually write new `web-platform-tests`. However, we do have lots of `web-platform-tests` for XHR, Fetch, and WebSocket.
  27
  28 ## Running Necko xpcshell-tests
  29
  30 - Local:
  31
  32   Run all xpcshell-tests:
  33
  34   ```console
  35   ./mach xpcshell-test netwerk/test/unit
  36   ```
  37
  38   Note that xpcshell-tests are run in parallel, sometimes we want to run them sequentially for debugging.
  39
  40   ```console
  41   ./mach xpcshell-test --sequential netwerk/test/unit
  42   ```
  43
  44   Run a single tests:
  45
  46   ```console
  47   ./mach xpcshell-test netwerk/test/unit/test_http3.js
  48   ```
  49
  50   Run with socket process enabled:
  51
  52   ```console
  53   ./mach xpcshell-test --setpref="network.http.network_access_on_socket_process.enabled=true" netwerk/test/unit/test_http3.js
  54   ```
  55
  56   We usually debug networking issues with `HTTP Logging`. To enable logging when running tests:
  57
  58   ```console
  59   MOZ_LOG=nsHttp:5 ./mach xpcshell-test netwerk/test/unit/test_http3.js
  60   ```
  61
  62 - Remote:
  63
  64   First of all, we need to know [Fuzzy Selector](https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html), which is the tool we use to select which test to run on try. If you already know that your code change can be covered by necko xpcshell-tests, you can use the following command to run all tests in `netwerk/test/unit` on try.
  65
  66   ```console
  67   ./mach try fuzzy netwerk/test/unit
  68   ```
  69
  70   Run a single test on try:
  71
  72   ```console
  73   ./mach try fuzzy netwerk/test/unit/test_http3.js
  74   ```
  75
  76   Sometimes we want to debug the failed test on try with logging enabled:
  77
  78   ```console
  79   ./mach try fuzzy --env "MOZ_LOG=nsHttp:5,nsHostResolver:5" netwerk/tesst/unit/test_http3.js
  80   ```
  81
  82   Note that it's not usually a good idea to enabling logging when running all tests in a folder on try, since the raw log file can be really huge. The log file might be not available if the size exceeds the limit on try.
  83   In the case that your code change is too generic or you are not sure which tests to run, you can use [Auto Selector](https://firefox-source-docs.mozilla.org/tools/try/selectors/auto.html) to let it select tests for you.
  84
  85 ## Debugging intermittent test failures
  86
  87 There are a lot of intermittent failures on try (usually not able to reproduce locally). Debugging these failures can be really annoying and time consuming. Here are some general guidelines to help you debug intermittent failures more efficiently.
  88
  89 - Identify whether the failure is caused by your code change.
  90   - Try to reproduce the intermittent failure locally. This is the most straightforward way. Adding `--verify` flag is also helpful when debugging locally (see this [document](https://firefox-source-docs.mozilla.org/testing/test-verification/index.html) for more details).
  91   - We can check the failure summery on try to see if there is already a bug filed for this test failure. If yes, it's likely this is not caused by your code change.
  92   - Re-trigger the failed test a few times and see if it passed. This can be easily done by clicking the `Push Health` button.
  93   - Looking for similar failures happening now on other submissions. This can be done by:
  94   ```
  95   click on failing job -> read failure summary -> find similar ones by other authors in similar jobs
  96   ```
  97   - To re-run the failed test suite more times, you could add `rebuild` option to `./mach try`. For example, the following command allows to run necko xpcshell-tests 20 times on try.
  98   ```
  99   ./mach try fuzzy netwerk/test/unit --rebuild 20
 100   ```
 101 - In the case that we really need to debug an intermittent test failure, see this [document](https://firefox-source-docs.mozilla.org/devtools/tests/debugging-intermittents.html) first for some general tips. Unfortunately, there is no easy way to debug this. One can try to isolate the failed test first and enable `HTTP logging` on try to collect the log for further analysis.
 102
 103 ## Writing Necko XPCShell tests
 104
 105 The most typical form of necko xpcsehll-test is creating an HTTP server and test your code by letting the server return some specific responses (e.g., `103 Early Hint`). We will only introduce how to write this kind of test in this document.
 106
 107 - Code at server side
 108
 109   After [bug 1756557](https://bugzilla.mozilla.org/show_bug.cgi?id=1756557), it is possible to create a `nodejs` HTTP server in your test code. This saves us some time for writing code at the server side by reusing the HTTP module provided by `nodejs`.
 110   This is what it looks like to create a simple HTTP server:
 111
 112   ```js
 113   let server = new NodeHTTPServer();
 114   await server.start();
 115   registerCleanupFunction(async () => {
 116     await server.stop();
 117   });
 118   await server.registerPathHandler("/test", (req, resp) => {
 119     resp.writeHead(200);
 120     resp.end("done");
 121   });
 122   ```
 123
 124   We can also create a `HTTP/2` server easily by replacing `NodeHTTPServer` with `NodeHTTP2Server` and adding the server certification.
 125
 126   ```js
 127   let certdb = Cc["@mozilla.org/security/x509certdb;1"].getService(
 128     Ci.nsIX509CertDB
 129   );
 130   addCertFromFile(certdb, "http2-ca.pem", "CTu,u,u");
 131   let server = new NodeHTTP2Server();
 132   ```
 133
 134 - Code at client side
 135
 136   The recommend way is to create and open an HTTP channel and handle the response with a `Promise` asynchronously.
 137   The code would be like:
 138
 139   ```js
 140   function makeChan(uri) {
 141     let chan = NetUtil.newChannel({
 142       uri,
 143       loadUsingSystemPrincipal: true,
 144     }).QueryInterface(Ci.nsIHttpChannel);
 145     chan.loadFlags = Ci.nsIChannel.LOAD_INITIAL_DOCUMENT_URI;
 146     return chan;
 147   }
 148   let chan = makeChan(`http://localhost:${server.port()}/test`);
 149   let req = await new Promise(resolve => {
 150     chan.asyncOpen(new ChannelListener(resolve, null, CL_ALLOW_UNKNOWN_CL));
 151   });
 152   ```
 153
 154   This is what it looks like to put everything together:
 155
 156   ```js
 157   add_task(async function test_http() {
 158     let server = new NodeHTTPServer();
 159     await server.start();
 160     registerCleanupFunction(async () => {
 161       await server.stop();
 162     });
 163     await server.registerPathHandler("/test", (req, resp) => {
 164       resp.writeHead(200);
 165       resp.end("done");
 166     });
 167     let chan = makeChan(`http://localhost:${server.port()}/test`);
 168     let req = await new Promise(resolve => {
 169       chan.asyncOpen(new ChannelListener(resolve, null, CL_ALLOW_UNKNOWN_CL));
 170     });
 171     equal(req.status, Cr.NS_OK);
 172     equal(req.QueryInterface(Ci.nsIHttpChannel).responseStatus, 200);
 173     equal(req.QueryInterface(Ci.nsIHttpChannel).protocolVersion, "http/1.1");
 174   });
 175   ```