vscode/test/smoke/README.md

# VS Code Smoke Test

## How to run

```
# Dev
npm run smoketest

# Specific build
npm run smoketest -- --build "path/to/code"

# Data Migration tests
npm run smoketest -- --build "path/to/code-insiders" --stable "path/to/code"
```

The script calls mocha, so all mocha arguments should work fine. For example, use `-f Git` to only run the `Git` tests.

By default, screenshots are not captured. To run tests with screenshots use the argument `--screenshots`.

## Pitfalls

- Beware of **state**. Invariably, your test suite will leave the workspace in a different state than the one it started
  with. Try to avoid these situations and strive to leave the workspace in the same state as before the test suite ran.

- Beware of **singletons**. This evil can manifest itself under the form of FS paths, TCP ports, IPC handles.
  Whenever writing a test, make sure it can run simultaneously with any other tests and even itself.
	All test suites should be able to run many times in parallel.

- Beware of **focus**. Never depend on DOM elements having focus using `.focused` classes or `:focus` pseudo-classes, since they will lose that state as soon as another window appears on top of the running VS Code window.
  A safe approach which avoids this problem is to use the `waitForActiveElement` API. Many tests use this whenever they need to wait for a specific element to _have focus_.

- **Never** wait longer than a couple of seconds for anything, unless it's justified. Think of it as a human
  using Code. Would a human take 10 minutes to run through the Search viewlet smoke test? Then, the computer
  should even be faster. **Don't** use `setTimeout` just because. Think about what you should wait for in the DOM to be ready, then wait for that instead.
update smoketest docs 2017-09-25 15:36:58 +00:00			`# VS Code Smoke Test`
Added step to run npm install 2017-06-30 13:32:45 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`## How to run`
smoke: update wiki 2017-09-08 17:04:52 +00:00
update smoketest launch 2017-09-04 09:32:41 +00:00			```
update smoketest docs 2017-09-25 15:36:58 +00:00			`# Dev`
smoke: update wiki 2017-09-08 17:04:52 +00:00			`npm run smoketest`
update smoketest launch 2017-09-04 09:32:41 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`# Specific build`
smoke: update wiki 2017-09-08 17:04:52 +00:00			`npm run smoketest -- --build "path/to/code"`
Update README.md 2017-06-30 14:21:34 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`# Data Migration tests`
smoke: update wiki 2017-09-08 17:04:52 +00:00			`npm run smoketest -- --build "path/to/code-insiders" --stable "path/to/code"`
			```
Moved contribution section to readme. 2017-06-01 13:50:23 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			The script calls mocha, so all mocha arguments should work fine. For example, use `-f Git` to only run the `Git` tests.
Moved contribution section to readme. 2017-06-01 13:50:23 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			By default, screenshots are not captured. To run tests with screenshots use the argument `--screenshots`.
Added explanation where to look for test data. 2017-06-14 12:06:42 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`## Pitfalls`
Moved contribution section to readme. 2017-06-01 13:50:23 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`- Beware of state. Invariably, your test suite will leave the workspace in a different state than the one it started`
			`with. Try to avoid these situations and strive to leave the workspace in the same state as before the test suite ran.`
Added smoke test source code. 2017-05-22 11:56:23 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			`- Beware of singletons. This evil can manifest itself under the form of FS paths, TCP ports, IPC handles.`
			`Whenever writing a test, make sure it can run simultaneously with any other tests and even itself.`
			`All test suites should be able to run many times in parallel.`
update smoketest launch 2017-09-04 09:32:41 +00:00
update smoketest docs 2017-09-25 15:36:58 +00:00			- Beware of focus. Never depend on DOM elements having focus using `.focused` classes or `:focus` pseudo-classes, since they will lose that state as soon as another window appears on top of the running VS Code window.
smoke: pitfalls 2017-09-25 20:46:02 +00:00			A safe approach which avoids this problem is to use the `waitForActiveElement` API. Many tests use this whenever they need to wait for a specific element to _have focus_.

			`- Never wait longer than a couple of seconds for anything, unless it's justified. Think of it as a human`
			`using Code. Would a human take 10 minutes to run through the Search viewlet smoke test? Then, the computer`
			should even be faster. Don't use `setTimeout` just because. Think about what you should wait for in the DOM to be ready, then wait for that instead.