Vorlon.JS is a remote debugging and testing tool for JavaScript. It helps you remotely load inspect, test and debug JavaScript code running on any device with a web browser: whether it's a games console, mobile device or fridge.
Vorlon.JS itself is a small web server you can run from your local machine, or install on a server for your team to access, that serves the Vorlon.JS dashboard and communicates with your remote devices. Installing the Vorlon.JS client in your web site or application is as easy as adding a single script tag.
Vorlon.JS can be extended with plugins which may add features to both the client and the dashboard, for example: feature detection, logging, and exception tracking.
To get started using Vorlon.JS you will need to install it from npm:
$ npm i -g vorlon
Once Vorlon.JS is done installing, you can now run the server:
$ vorlon
The Vorlon server is running
With the server running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.
Before you can start debugging your app you have to enable it to communicate to the Vorlon.JS Server by adding this script tag to your application’s html:
<script src="http://localhost:1337/vorlon.js"></script>
You can also open the sample page to test that your dashboard is working. You should see the client appear in your dashboard when you open that page.
If you want to get an unminified version of the plugins on your web page, you can use the following script tag:
<script src="http://localhost:1337/vorlon.max.js"></script>
You can have more control on the moment the client side part is starting by using the autostartdisabled version:
<script src="http://localhost:1337/vorlon.autostartdisabled.js"></script>
which also exist with the unminified version of the code:
<script src="http://localhost:1337/vorlon.max.autostartdisabled.js"></script>
Once this is done, you can start the vorlon client and connect it to the dashbard of you choice using the session id you want:
VORLON.Core.StartClientSide("http://localhost:1337", "default");
If you do not want to use a specific plugin in your dashboard and disable it also on the client part, you can use the config.json file on the server. To be able to do this, you need to use Vorlon.js downloaded and installed from the GitHub repository. You can also modify the package downloaded from npm but this is not recommended.
The file is located on the following folder :
Server/config.json
By default, it looks like this :
{
"includeSocketIO": true,
"useSSLAzure": false,
"useSSL": true,
"SSLkey": "cert/server.key",
"SSLcert": "cert/server.crt",
"plugins": [
{ "id": "CONSOLE", "name": "Interactive Console", "panel": "bottom", "foldername" : "interactiveConsole", "enabled": true},
{ "id": "DOM", "name": "Dom Explorer", "panel": "top", "foldername" : "domExplorer", "enabled": true },
{ "id": "MODERNIZR", "name": "Modernizr","panel": "bottom", "foldername" : "modernizrReport", "enabled": true },
{ "id" : "OBJEXPLORER", "name" : "Obj. Explorer","panel": "top", "foldername" : "objectExplorer", "enabled": true },
{ "id" : "XHRPANEL", "name" : "XHR","panel": "top", "foldername" : "xhrPanel", "enabled": true },
{ "id" : "NGINSPECTOR", "name" : "ngInspector","panel": "top", "foldername" : "ngInspector", "enabled": false }
]
}
It is obviously using the JSON (JavaScript Simple Object Notation) format and is easy to understand: each line in the "plugins" array represents a plugin.
For instance, you can change the folder where the plugin is installed. This folder has to be located under:
Server/public/vorlon/plugins
By convention, this name needs to be the same as the JavaScript file for the plugin for either the max file:
{FOLDERNAME}.js
and the min version:
{FOLDERNAME}.min.js
You can also choose in which panel the plugin should be displayed using the "panel" property. It can be either "bottom" or "top".
You can add and remove plugins here. It will impact the dashbard by not displaying a removed plugin and also the client JavaScript file which is sent to the client website.
We also added the option to NOT automatically include socket.io in the script returned to the client. You can disable socket.io embedding by setting:
"includeSocketIO": false
If you want to support SSL and HTTPS, you just have to set "useSSL" to true and then define SSLKey and SSLcert files.
You can change the base URL path in config.json.
"baseURL": "/your/directory"
You can activate a basic authentication on the Vorlon.js dashboard by adding 3 values to the config.json file.
"activateAuth": true,
"username": "CHANGEHERE",
"password": "CHANGEHERE"
If the "activateAuth" is set to true, you will be redirected to the login page on the first navigation on the dashboard. You then need to give the information set on the "username" et "password" settings value.
This allows you to configure a remote Vorlon.js dashboard without risking everyone to access it.
If you want to run the server with SSL support proceed as follows:
6.Exit and save JSON file
{
"useSSLAzure: false,
"useSSL": true,
"SSLkey": "server/cert/server.key",
"SSLcert": "server/cert/server.crt",
"includeSocketIO": true,
"plugins":
...
}
5.Navigate with https protole on your Azure WebSite
{
"useSSLAzure: true,
"useSSL": false,
"SSLkey": "",
"SSLcert": "",
"includeSocketIO": true,
"plugins":
...
}
Edit your nginx.conf, find server { and use this (don't forget to change the paths below to your own paths).
server {
server_name vorlon;
location ~ ^/(fonts/|images/|javascripts/|stylesheets/|vorlon/|vorlon.dashboardManager.js|robots.txt|humans.txt|favicon.ico) {
root /PATH/TO/Vorlonjs/Server/public;
access_log off;
expires 24h;
}
location /test {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
proxy_pass http://localhost:1337;
}
location /socket.io {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
proxy_pass http://localhost:1337;
}
The Vorlon.JS dashboard is designed to help debug and test remote JavaScript applications and the UI is geared towards that goal. The dashboard has two major sections, the client summary view and the plugin view.
The client summary view shows what the current session and client id are currently active and a list of available clients that you can work with. The Identify a client button quickly allows you to see which remote client browser tab or window you are currently working with.
The plugin view is where all the action is! The console is the only plugin that has a fixed location at the bottom of the dashboard and all other plugins will present themselves across the top as tabs.
The console tab will stream console messages from the client to the dashboard that you can use for debugging. Anything logged with console.log(), console.warn() or console.error() will appear in the dashboard.
You can also interact with the remote webpage by typing code into the input. Code entered will be evaluated in the context of the page.
The DOM explorer shows you the dom of the remote webpage. You can inspect the DOM, clicking on nodes will highlight them in the host webpage, and if you select one you can also view and modify its css properties.
The Modernizr tab will show you the supported browser features as reported by Modernizr. You can use this to determine what features are actually available. This might be particularly useful on unusual mobile devices, or things like games consoles. You can use the search filter to select only specific features.
The Object explorer tab will show you all JavaScript variable living on the remote page. You can click on object to see inner properties.
The XHR panel will help you analyze XHR calls sent by your devices. You can track status code and others useful information.
The ngInspector tab is a tool that will display your Angular.js scopes. You can see inner scopes and even ngRepeat constructs.
The Network Monitor brings the ability to see all network exchanges done between the browser and the web server. It provides the resource name, the server domain, the type of request, the duration in milliseconds and a nice visual timeline.
The Resources Explorer provides information about what is locally stored on the client instance such as sessions, cookies, and local storage. This can be really useful when you want to debug local cache or login / persistent user data issues.
The unit test plugin helps you to run qUnit tests remotely from the Dashboard. You can upload a JavaScript file containing your tests or type test directly in the plugin. Hit the "Run tests" button and you get the results in the dashboard !
This displays you a lot of informations coming from the client such as the user agent, the size of the screen, the pixel per points, etc. The informations are dynamically updated if you redimension your browser.
This plugins checks for many rules related to best practices and web standards for your website. It can be usefull to detect various implementation details like accessibility, css checks like prefixes, ... The rules system and extensible. It means that you could contribute additionnal rules, or build rules for yourself based on your own needs.
This displays you informations from your node.js process such as the required node modules, the node.js version, the operating system of your server, etc. The plugins also allow you to see the memory usage of your process through a line chart.
The Express Debugger allows you to debug your Node.js Express-based application, you can see the request flow, the routes, the sessions and the locals variable of your application.
Vorlon.JS has been designed so that you can extend the dashboard and client application easily by writing or installing additional plugins. These can add extra panes to the dashboard which can communicate bi-directionally with the client application. The console, dom inspector and modernizr panes that come bundled with Vorlon.JS are all plugins themselves.
To write plugins, you currently need to clone and run Vorlon.JS from source.
These commands will clone the repo, install dependencies, and run the VorlonJS server from source:
git clone https://github.com/MicrosoftDX/Vorlonjs.git
cd Vorlonjs
npm install
npm start
For further documentation on developing on Vorlon.JS, check the full readme in the repo.
A Vorlon.JS plugin is based on two Typescript classes, that will be loaded in both the client and dashboard. They have to extend from the Vorlon.ClientPlugin class and the Vorlon.DashboardPlugin class. It may also load html and css into the dashboard to define a panel. You can then write code for both the dashboard and client that can communicate bidirectionally to create whatever features you need.
To make it easy to get started, we’ve created a sample plugin. This adds an input field to the dashboard, that, when you type something and hit return, sends the message to your client browser, which will reverse the string and send it back, to be rendered in the dashboard. It’s just a simple example to show you how to create and communicate in a plugin. You should check the sample plugin’s readme for information about how to enable it, and then read the sample client plugin’s code and the sample dashboard plugin's code to see how you might modify it for your own needs.
We are still working on making it easy to install and run third-party plugins for Vorlon.JS. At the moment, you will need to write and compile plugins in a checked out version of vorlon as above, but we want to make it really easy for you to publish and use plugins with Vorlon.JS. If you have ideas on how we can improve this file an issue on github.
In the meantime, if you've developed a plugin that you think could go in Vorlon.JS core, submit a pull request.
How to create a plugin by Etienne Margraff
Sometimes you must audit, test, or debug a website in production and you don't have Vorlon script injected in your pages. For all such cases, you could now use Vorlon "proxy" feature to open your site.
The proxy is a tool built with node.js, running server side on a separate process (and therefore a separate port or domain if you must deploy it). When the proxy is called with a target url, it will forward this http call (and all subsequent calls) to the target. The proxy will injects Vorlon's client script in the page for you in the meantime. To manage subsequent calls for resources from the website (like css, scripts, images, ...), the proxy create a cookie on first call with the target url. The (necessary) use of a cookie means that it is unadvised to run multiple Vorlon inspection using proxy with the same browser instance (because this cookie will be shared among browser tabs).
First you must check that the proxy has been enabled. Open config.json and verify that "enableWebproxy" is set to true, and start your Vorlon server (using "npm start" for example). That's the only thing you must have to do. If you run the proxy locally, you could go to http://localhost:1337/httpproxy to open a helper page. The proxy itself will listen on port 5050 (by default). In case of trouble, look at the console for your server. At the very beginning you must have a trace indicating that the server and the proxy have started, and which port they are running on.
Vorlon server and proxy resides on different processes and could be deployed separately. To work properly, the proxy must be listening at the root of a http domain. The proxy cannot work if it's set on a path like "http://vorlonjs.com/documentation/". This is due to the fact that inspected web pages may have url relative to the httpdomain (url starting with "/"). If the proxy is not listening at the root, it won't be able to catch those calls.
If you want to host a Vorlon instance with the proxy feature, their are a few configurations that you may find usefull : "vorlonServerURL" is used by the proxy to build the url of Vorlon client script "vorlonProxyURL" is used by the Vorlon server to send requests to the proxy
if empty, "vorlonServerURL" and "vorlonProxyURL" default to localhost with the proper port.
Vorlon.js is versatile enough to be used with Node.js applications as well.
But because node.js does not provide DOM elements, all plugins can not be used when debugging Node.js applications.
This is why some plugins are flagged with nodeCompliant=true in the catalog file:
{ "id" : "XHRPANEL", "name" : "XHR","panel": "top", "foldername" : "xhrPanel", "enabled": true, "nodeCompliant": true }
To do so, you have to npm install vorlon-node-wrapper. Once done, you can add this code to your application:
var vorlonWrapper = require("vorlon-node-wrapper");
var serverUrl = "http://localhost:1337";
var dashboardSession = "default";
//This will connect to your Vorlon.js instance (serverUrl) and download the Vorlon.node.js client file (Vorlon for node).
vorlonWrapper.start(serverUrl, dashboardSession, false);
// Your code
// ...
You can also use the asynchronous version of the start function:
var vorlonWrapper = require("vorlon-node-wrapper");
var serverUrl = "http://localhost:1337";
var dashboardSession = "default";
//This will connect to your Vorlon.js instance (serverUrl) and download the Vorlon.node.js client file (Vorlon for node).
vorlonWrapper.start(serverUrl, dashboardSession, true, function (result, errorMessage) {
// Your code
// ...
});
If you plan to create a plugin that could work with Node.js, the only think you have to do is to mark it as compliant in the catalog.json file.
Regarding the code itself, you can use Vorlon.Tools.IsWindowAvailable to determine if you are running in a browser context (where window object is available) or in a node.js context (where global object is available).
Vorlon.JS is a fully open source project. It is licensed with the MIT License.
For information on how to develop on the Vorlon.JS server/client itself, and how to contribute, please read the README and CONTRIBUTING files over at the github repo.