Writing an Integration Test

Background

There are a few key background points that will be helpful to test-writers:

• Every Nuclide integration test is located in the top-level spec/ directory.
• To ensure that each test runs with a clean require-cache and that tests do not create or alter state of the atom global for subsequent tests, the test script used to run integration tests (./scripts/dev/test --run-integration-tests) will effectively run apm test on each integration test as though it were the only test in the spec/ directory. For details on how this is done see: 2a021bb. The takeaway is that you should never run apm test in the top-level Nuclide/ directory and expect it to run the integration tests correctly.
• Because we don't want to pollute state between tests and apm test doesn't do a good job of resetting state, you should always have exactly one test per file. For more details, read the next section: "Writing a Test".
• To run just one test, perhaps while developing it, use atom --test with the specific filename as described below.

Writing a Test

There are a few guidelines to follow for writing integration tests:

• Put your integration test in the top-level spec/ directory.
• Generally, only have one test per file.
  • Essentially, you should have a single describe, wrapping a single it, containing your integration test. However, you can have as many expect, waitsFor, waitsForPromise, and runs as you need within this it call.
  • However, you should group related tests that either vary in a few parameters or that follow a common user sequence. For example, a test that moves a pane up, down, back up, left, right, back to the left, etc should be in a single test file.
• Any test-only code shared between integration tests must be placed under spec/lib/ to whitelist it from the test isolation logic.
• Copy the template test Nuclide/spec/example-integration-spec.js and fill it in with your desired test contents.

There are several helpful utilities to get you up and running, located in the nuclide-integration-test-helpers package. These include utilites for setting up temporary mercurial or flow projects, starting a local instance of the nuclide or flow servers, adding or removing local or remote projects, and activating or deactivating nuclide packages. Doc-blocks are included for each function where they are defined.

Debugging a Test

IMPORTANT: Since we run integration tests as though there is only one test in the spec/ directory, make sure to use fdescribe instead of describe when debugging, so that only your test runs.

For debugging your integration test, it is highly recommended that you use the built-in atom spec runner. You can launch this with cmd + alt + ctrl + P. This opens up a separate window that runs the specs for the package you're in. The spec runner lets you use the chrome JS debugger to debug your test. You can open it the usual way with cmd + alt + I.

Running Integration Tests Locally

If you want to run all the integration tests locally, then use ./scripts/dev/test --run-integration-tests. This is the same command that sandcastle runs. Typically integration tests have a lot of log-spew which can be safely ignored.

If a test consistently fails for you, check that you have the external dependencies installed on your machine. For example, if the clang test fails, make sure you have xcode and buck installed on your machine.

Running Single Tests

• atom --dev --test path/to/test
• atom --dev --test --v=-3 path/to/test removes the chromium log noise
• Run any file in the "Run Package Specs" window (including integration tests) by opening the file and running require('electron').ipcRenderer.send('run-package-specs', atom.workspace.getActivePaneItem().getPath());.