cesium1.7.zip

# Testing Guide Our development culture is committed to testing. CesiumJS is used in diverse use cases on a wide array of platforms so it is important for it to be well tested. As of CesiumJS 1.35, CesiumJS has over 8,800 tests with 93% code coverage. CesiumJS has as much test code (126K lines) as engine code (126K). We are unaware of any other project of this size and lifetime and with this many contributors that has similar stats. All new code should have 100% code coverage and should pass all tests. Always run the tests before opening a pull request. - [Running the Tests](#running-the-tests) - [Run All Tests](#run-all-tests) - [Run with WebGL validation](#run-with-webgl-validation) - [Run with WebGL stub](#run-with-webgl-stub) - [Select a Test to Run](#select-a-test-to-run) - [Run Only WebGL Tests](#run-only-webgl-tests) - [Run Only Non-WebGL Tests](#run-only-non-webgl-tests) - [Run All Tests against Combined File (Run All Tests against Combined File with Debug Code Removed)]() - [Run All Tests with Coverage](#run-all-tests-against-combined-file-run-all-tests-against-combined-file-with-debug-code-removed) - [Running Tests on the Command Line with Karma](#running-tests-on-the-command-line-with-karma) - [Testing Previous Versions of CesiumJS](#testing-previous-versions-of-cesium) - [`testfailure` Label for Issues](#testfailure-label-for-issues) - [Writing Tests](#writing-tests) - [Directory Organization](#directory-organization) - [Bottom-Up Unit Testing](#bottom-up-unit-testing) - [Test Code is Code](#test-code-is-code) - [Testing Basics](#testing-basics) - [Comparing Floating-Point Values](#comparing-floating-point-values) - [Testing Exceptions](#testing-exceptions) - [Before and After Tests and Suites](#before-and-after-tests-and-suites) - [Rendering Tests](#rendering-tests) - [GLSL](#glsl) - [Spies](#spies) - [Test Data and Services](#test-data-and-services) - [Promises](#promises) - [Mocks](#mocks) - [Categories](#categories) - [Manual Testing](#manual-testing) - [Pragmatic Advice](#pragmatic-advice) - [Start with a Similar (Small) Test](#start-with-a-similar-small-test) - [Debugger-Aided Incremental Improvements](#debugger-aided-incremental-improvements) - [Resources](#resources) ## Running the Tests The CesiumJS tests are written in JavaScript and use [Jasmine](http://jasmine.github.io/), a behavior-driven testing framework. Jasmine calls an individual test, e.g., a function with one or more assertions, a **spec** (however, the Cesium team usually still say "test"), and a group of related tests, e.g., all the tests for `Cartesian3`, a **suite**. Jasmine also calls an assertion, an **expectation**. When running CesiumJS locally, browse to [http://localhost:8080/](http://localhost:8080/) and there are several test options: ### Run All Tests Runs all the tests. As of CesiumJS 1.15, on a decent laptop, they run in about a minute in Chrome. It is important that the tests run quickly so we run them often. When all the tests pass, the page looks like this:  When one or more tests fail, the page looks like this:  In this case, the number of failing tests is listed at the top, and details on each failure are listed below, including the expected and actual value of the failed expectation and the call stack. The top several functions of the call stack are inside Jasmine and can be ignored. Above, the file and line of interest for the first failing test starts with an `@`: ``` @http://localhost:8080/Specs/Renderer/FramebufferSpec.js:637:13 ``` Click on the failed test to rerun just that test. This is useful for saving time when fixing an issue as it avoids rerunning all the tests. Always rerun _all_ the tests before opening a pull request. #### Run with WebGL validation The link to **Run with WebGL validation** passes a query parameter to the tests to enable extra low-level WebGL validation such as calling `gl.getError()` after each WebGL call. We use this when doing the monthly CesiumJS release and when making changes to CesiumJS's renderer. #### Run with WebGL stub The **Run with WebGL stub** link passes a query parameter to the tests to use CesiumJS's WebGL stub. This makes all WebGL calls a noop and ignores test expectations that rely on reading back from WebGL. This allows running the tests on CI where a reasonable WebGL implementation is not available and still getting full code coverage albeit not all verification. ### Select a Test to Run This option loads the test page without running any tests.  We can then use the browser's built-in search to find a test or suite and run only that. For example, below just the tests for `Cartesian3` were run.  This uses a query parameter to select the test/suite to run so refreshing the page will run just that test/suite again. Often when developing, it is useful to run only one suite to save time, instead of all the tests, and then run all the tests before opening a pull request. ### Run Only WebGL Tests Suites can have a category associated with them. This option runs all tests in the `WebGL` category, which includes all tests that use WebGL (basically anything that requires creating a `Viewer`, `CesiumWidget`, `Scene`, or `Context`). ### Run Only Non-WebGL Tests Likewise, this option runs all tests not in the WebGL category. Perhaps surprisingly, this is the bulk of CesiumJS tests, which include math and geometry tests, imagery provider tests, data source tests, etc. These tests run quickly (for example, 15 seconds compared to 60) and are very reliable across systems since they do not rely on the underlying WebGL implementation, which can vary based on the browser, OS, driver, and GPU. ### Run All Tests against Combined File (Run All Tests against Combined File with Debug Code Removed) Most test options load CesiumJS using the individual source files in the `Source` directory, which is great for debugging. However, many users build apps using the built Cesium.js in `Build/Cesium` (which is created, for example, by running `npm run combine`). This option runs the tests using this instead of individual CesiumJS source files. The **Run All Tests against Combined File with Debug Code Removed** is the same except it is for use with the release version of the built Cesium.js (which is created, for example, by running `npm run combineRelease`). The release version has `DeveloperError` exceptions optimized out so this test option makes `toThrowDeveloperError` always pass. See the [Build Guide](https://github.com/CesiumGS/cesium/blob/master/Documentation/Contributors/BuildGuide/README.md#build-scripts) for all the CesiumJS build options. ## Run Coverage We use [istanbul](https://istanbul.js.org/) via [karma-coverage](https://github.com/karma-runner/karma-coverage) to generate code coverage reports. It is especially important to have outstanding code coverage since JavaScript doesn't have a compiler and linker to catch early errors. To generate a coverage report, run: `npm run coverage`. This will place a report inside of the `Build/Coverage/<browser>` folder and open your default browser with the result. You'll see a source tree that matches Cesium's own code layout. Each directory shows aggregated results for all files it contains.  Click on a directory to see results for each file in that directory. Click on a specific file to see line-by-line coverage for just that file. For example, here is `Core/AssociativeArray`:  In the left margin, green indicates how many times a line was executed. Many lines, such as comments and semicolons, are not colored since they are not executable. For the `contains` function above - `AssociativeArray.prototype.contains = function(key) {` is executed once when CesiumJS is loaded to assign the `contains` function to the `AssociativeArray`'s prototype. - The `if` statement and return statement are executed 8,022 times. - The `