Merge pull request #1 from AlexanderMoskovkin/master

Initial commit

Author: AlexanderMoskovkin

.eslintignore

@@ -0,0 +1 @@
+lib/log-update-async-hook/

.eslintrc.json

@@ -0,0 +1,26 @@
+{
+  "env": {
+    "es6": true,
+    "node": true
+  },
+  "extends": "eslint:recommended",
+  "rules": {
+    "indent": [
+      "error",
+      4
+    ],
+    "linebreak-style": [
+      "error",
+      "unix"
+    ],
+    "quotes": [
+      "error",
+      "single"
+    ],
+    "semi": [
+      "error",
+      "always"
+    ],
+    "no-console": 0
+  }
+}

.gitattributes

@@ -0,0 +1,10 @@
+* text=auto
+*.sh text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.css text eol=lf
+*.html text eol=lf
+*.md text eol=lf
+
+*.png binary
+*.ico binary

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.idea
+yarn.lock
+package-lock.json

README.md

@@ -1 +1,174 @@
-# testcafe-live
+# TestCafe Live
+
+See instant feedback when working on tests.
+
+## What is it?
+
+TestCafe Live provides a service that keeps the TestCafe process and browsers opened the whole time you are
+working on tests. Changes you make in code immediately restart the tests. That is, TestCafe Live allows you to see test results instantly.
+
+## Install
+
+TestCafe Live is a CLI tool. To start using it, you need to install both `testcafe` and `testcafe-live`:
+
+```sh
+npm install testcafe testcafe-live -g
+```
+
+If you have already installed the `testcafe` module (version `0.18.0` or higher) you can install only `testcafe-live`:
+
+```sh
+npm install testcafe-live -g
+```
+
+This installs modules on your machine [globally](https://docs.npmjs.com/getting-started/installing-npm-packages-globally).
+
+If necessary, you can add these modules locally to your project:
+
+```sh
+cd <your-project-dir>
+npm install testcafe testcafe-live --save-dev
+```
+
+If you have installed `testcafe-live` locally to your project, add an npm script to `package.json` to run tests:
+
+```json
+"scripts": {
+  "testcafe-live": "testcafe-live chrome tests/"
+},
+```
+
+```sh
+npm run testcafe-live
+```
+
+## How to use
+
+Run tests with `testcafe-live` in the same way as you do with `testcafe`:
+
+```sh
+testcafe-live chrome tests/
+```
+
+Use [standard `testcafe` arguments](https://devexpress.github.io/testcafe/documentation/using-testcafe/command-line-interface.html) to run tests with `testcafe-live`. It opens the required browsers, run tests
+there, shows the reports and waits for your further actions.
+
+TestCafe Live watches files that you pass as the `src` argument and files that are required in them. Once you make changes in files and save them, TestCafe Live immediately reruns your tests.
+
+When the tests are done, browsers stay on the last opened page so you can work with it and explore it by using the browser's developer tools.
+
+### Commands
+
+- ctrl+s - stop current test run;
+- ctrl+r - restart current test run;
+- ctrl+w - turn off/on files watching;
+- ctrl+c - close opened browsers and terminate the process.
+
+## Features
+
+- TestCafe Live watches files with tests and helper modules rerunning the tests once changes are saved;
+- You can explore the tested page in the same browser when tests are finished;
+- If tests authenticate into your web application using [User Roles](https://devexpress.github.io/testcafe/documentation/test-api/authentication/user-roles.html), you do not need to execute login actions every test run, it saves your working time;
+- Use the same API as TestCafe;
+- CLI interface allows you to stop test runs, restart them and pause file watching;
+- You can use TestCafe Live with any browsers (local, remote, mobile or headless).
+
+## Why TestCafe Live is a separate repository
+
+TestCafe Live is developed by the TestCafe Team as an addition to the main TestCafe module. Keeping it a separate project provides many benefits:
+
+- We can deliver new functionality once it's ready regardless of the TestCafe release cycle;
+- We can get feedback early and make new releases as fast as necessary to provide the best experience for developers;
+- We can try experimental features that may be added to TestCafe later and get early feedback about them.
+
+### Will this functionality be released in the main TestCafe tool
+
+We will decide when we have more feedback and when we consider TestCafe Live finished and stable. Since TestCafe is a test runner it is possible
+that `live` mode will exist as an additional tool.
+
+## Tips and Tricks
+
+### Which path should I pass as the `src` argument
+
+You can pass either a path to a file with tests or a path to a directory.
+
+If you specify a single file, `testcafe-live` will watch changes in it. Additionally, it will watch changes in files that are required from this file. Once you save changes in this file or in one of the required files, tests are rerun.
+
+```sh
+testcafe-live chrome tests/test.js
+```
+
+You can also pass a path to a directory where your files with tests are stored.
+
+```sh
+testcafe chrome tests/
+```
+
+TestCafe will watch all files in this directory and all files that are required from there and restart all tests once one of them is changed.
+
+### I have lots of tests but would like to restart only one
+
+When you work on a particular test, just add the `.only` call for it:
+
+```
+test.only('Current test', async t => {});
+```
+
+Once you are done with it and ready to run the whole suite, just remove the `.only` directive and save the file.
+
+### Should I use TestCafe Live or TestCafe for CI
+
+TestCafe Live is designed to work with tests locally. So use the main `testcafe` module for CI.
+
+### How avoid performing authentication actions every run
+
+If you test a page with a login form, you need to enter credentials at the beginning of each test. TestCafe provides [User Roles](https://devexpress.github.io/testcafe/documentation/test-api/authentication/user-roles.html) to impove your experience here.
+
+At first, create a user role with authentication steps in a separate file and export it:
+
+```js
+// roles.js
+
+import { Role, t } from 'testcafe';
+
+export loggedUser = Role('http://mysite/login-page', async t => {
+  await t
+    .typeText('#login-input', 'my-login')
+    .typeText('#password-input', 'my-input')
+    .click('#submit-btn');
+}, { preserveUrl: true });
+```
+
+Import the role into a file with tests and use it in the `beforeEach` function:
+
+```js
+// test.js
+import { loggedUser } from './roles.js';
+
+fixture `Check logged user`
+    .page `http://mysite/profile`
+    .beforeEach(async t => {
+      await t.useRole(loggedUser);
+    });
+    
+test('My test with logged user', async t => {
+    // perform any action here as a logger user
+});
+```
+
+When you run tests with TestCafe Live for the first time, role initialization steps will be executed and your tests will run with an authorized user profile. If you change the test file, the next run will skip role initialization and just load the page with saved
+credentials. If you change code in a role, it will be 'refreshed' and role initialization steps will be executed at the next run.
+
+### I'd like to make changes in several files before running tests
+
+Just focus your terminal and press `ctrl+p`. TestCafe Live will not run tests until your press `ctrl+r`.
+
+## Feedback
+
+Report issues and leave proposals regarding this 'live' mode in this repository. Please address all issues about TestCafe to the main [TestCafe repository](https://github.com/DevExpress/testcafe/issues).
+If you like this mode please let us know. We will be glad to hear your proposals on how to make it more convinient.
+Feel free to share your experience with other developers.
+
+## Author
+
+Developer Express Inc. ([https://devexpress.com](https://devexpress.com))

bin/testcafe-live.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+'use strict';
+
+require('../lib');

lib/client/.eslintrc.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "browser": true
+  }
+}

lib/client/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+(function () {
+    // NOTE: enable interaction with a page when the last test is completed
+    window.setTimeout(function () {
+        const UNLOCK_PAGE_FLAG = 'testcafe-live|driver|unlock-page-flag';
+
+        // TestCafe > 0.18.5 required
+        const testCafeDriver = window['%testCafeDriverInstance%'];
+        const testCafeCore   = window['%testCafeCore%'];
+        const hammerhead     = window['%hammerhead%'];
+
+        testCafeDriver.setCustomCommandHandlers('unlock-page', function () {
+            testCafeCore.disableRealEventsPreventing();
+
+            testCafeDriver.contextStorage.setItem(UNLOCK_PAGE_FLAG, true);
+
+            return hammerhead.Promise.resolve();
+        });
+
+        const chain = testCafeDriver.contextStorage ? hammerhead.Promise.resolve() : testCafeDriver.readyPromise;
+
+        chain.then(function () {
+            if (testCafeDriver.contextStorage.getItem(UNLOCK_PAGE_FLAG))
+                testCafeCore.disableRealEventsPreventing();
+        });
+    });
+})();

lib/controller.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const EventEmitter = require('events');
+const TestRunner   = require('./test-runner');
+const FileWatcher  = require('./file-watcher');
+const logger       = require('./logger');
+
+class Controller extends EventEmitter {
+    constructor () {
+        super();
+
+        this.REQUIRED_MODULE_FOUND_EVENT = 'require-module-found';
+
+        this.testRunner = null;
+        this.src        = null;
+
+        this.running        = false;
+        this.restarting     = false;
+        this.watchingPaused = false;
+        this.stopping       = false;
+    }
+
+    init (tcArguments) {
+        this._initFileWatching(tcArguments.src);
+
+        this.testRunner = new TestRunner(tcArguments, logger);
+
+        this.testRunner.on(this.testRunner.TEST_RUN_STARTED, () => logger.testsStarted());
+
+        this.testRunner.on(this.testRunner.TEST_RUN_DONE_EVENT, e => {
+            logger.testsFinished();
+
+            this.running = false;
+
+            if (e.err)
+                console.log(`ERROR: ${e.err}`);
+        });
+
+        this.testRunner.on(this.testRunner.REQUIRED_MODULE_FOUND_EVENT, e => {
+            this.emit(this.REQUIRED_MODULE_FOUND_EVENT, e);
+        });
+
+        this.testRunner.init()
+            .then(() => {
+                logger.intro();
+                this._runTests();
+            });
+    }
+
+    _initFileWatching (src) {
+        const fileWatcher = new FileWatcher(src);
+
+        this.on(this.REQUIRED_MODULE_FOUND_EVENT, e => fileWatcher.addFile(e.filename));
+
+        fileWatcher.on(fileWatcher.FILE_CHANGED_EVENT, () => {
+            if (!this.watchingPaused)
+                this._sourcesChanged();
+        });
+    }
+
+    _sourcesChanged () {
+        if (this.running)
+            return;
+
+        this._runTests(true);
+    }
+
+    _runTests (sourceChanged) {
+        logger.runTests(sourceChanged);
+
+        this.running = true;
+        this.testRunner.run();
+    }
+
+    toggleWatching () {
+        this.watchingPaused = !this.watchingPaused;
+
+        logger.toggleWatching(!this.watchingPaused);
+    }
+
+    stop () {
+        if (!this.testRunner || !this.running) {
+            logger.nothingToStop();
+
+            return Promise.resolve();
+        }
+
+        logger.stopRunning();
+
+        return this.testRunner.stop()
+            .then(() => {
+                this.running = false;
+            });
+    }
+
+    restart () {
+        if (this.restarting)
+            return;
+
+        if (!this.running)
+            this._runTests();
+        else {
+            this.restarting = true;
+
+            this.stop().then(() => {
+                logger.testsFinished();
+
+                this.restarting = false;
+                this.running    = false;
+
+                this._runTests();
+            });
+        }
+    }
+
+    exit () {
+        if (this.stopping)
+            return Promise.resolve();
+
+        logger.exit();
+
+        this.stopping = true;
+
+        return this.testRunner ? this.testRunner.exit() : Promise.resolve();
+    }
+}
+
+module.exports = new Controller();