Skip to content
TypeScript JavaScript Kotlin Java C++ Python Other
Branch: master
Clone or download
csilvestrini Add `run` subcommand for sigh (#3855)
* Add `run` subcommand for sigh

This lets you add new scripts with less boilerplate (just add a new line
to the `scripts` variable). Scripts can be run via:

./tools/sigh run <script name> <rest of args>

(I'm going to be adding additional scripts to be invoked by bazel soon, so this makes that slightly easier.)

* Fix bug: !scriptPath
Latest commit c1219ed Oct 22, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
build_defs Move src_kt into the main repo WORKSPACE (#3835) Oct 22, 2019
config Lint warning for trailing whitespace and eof newline (#3680) Oct 3, 2019
design Rename Variable to Singleton (#3102) May 31, 2019
devtools Fix invisible pec-log (#3763) Oct 12, 2019
extension Use strictEqual and strictNotEqual for all tests (#3321) Jul 15, 2019
javaharness Tidy up javaharness WORKSPACE rules (#3837) Oct 22, 2019
modalities/dom Lint warning for trailing whitespace and eof newline (#3680) Oct 3, 2019
particles Unified syntax and tests for particle slot connections (#3847) Oct 22, 2019
shells Entity id bug (#3836) Oct 22, 2019
src Add tokens to drivers. (#3853) Oct 22, 2019
src_kt Create a `common` package. (#3848) Oct 22, 2019
tools Add `run` subcommand for sigh (#3855) Oct 22, 2019
.appveyor.yml Lock appveyer to 10.15.3 until node-webcrypto-ossl module starts work… Jun 12, 2019
.bazelignore Move src_kt into the main repo WORKSPACE (#3835) Oct 22, 2019
.clang-format Run clang-format over extension Jan 5, 2018
.dockerignore The Raulnarok PR of 2018 (#2389) Dec 6, 2018
.editorconfig Add an editorconfig configuration for easier IDE use - http://editorc… Sep 14, 2018
.eslintignore Fix dynamic memory configuration for wasm particles. (#3148) Jun 7, 2019
.eslintrc.json Start the process of moving to eslint based tyepscript linting (#3015) May 15, 2019
.gitignore Set up src_kt directory, get the ball rolling with Crdts in Kotlin. (#… Oct 14, 2019
.nojekyll .nojekyll so arcs-live can serve from node_modules (#2688) Feb 13, 2019
.nvmrc Exercise setup script (#3391) Aug 15, 2019
.travis.yml Move src_kt into the main repo WORKSPACE (#3835) Oct 22, 2019
BUILD.bazel Fix bug in //:all_srcs glob (#3856) Oct 22, 2019
Dockerfile Improve CI testing, fix and add server tests (#2182) Nov 5, 2018
LICENSE Standardize and enforce License headers (#3079) May 30, 2019 Update Bash Setup Script (#3596) Sep 23, 2019
WORKSPACE Move src_kt into the main repo WORKSPACE (#3835) Oct 22, 2019
cloudbuild.yaml Improve CI testing, fix and add server tests (#2182) Nov 5, 2018
js-green-licenses.json Upgrade PouchDB and update whitelisted licenses (#3214) Jun 21, 2019
package-lock.json Particle API cleanup: collapse handle helpers into set, add, remove, … Oct 9, 2019
package.json Install deps of devServer when running npm start (#3750) Oct 10, 2019
rollup.config.js Lint warning for trailing whitespace and eof newline (#3680) Oct 3, 2019 Move src_kt into the main repo WORKSPACE (#3835) Oct 22, 2019
tsconfig.json Add vs code extension (#3534) Sep 10, 2019
tslint.json Introduce new expressjs-based server package for personal cloud use (#… Sep 11, 2018
webpack.config.js Standardize and enforce License headers (#3079) May 30, 2019

Build Status AppVeyor Build status


A hosted version of Arcs is available in both tagged and bleeding edge forms. Neither is stable -- the runtime, database and front-end are all iterating rapidly.

TypeDoc generated documentation is available for Arcs Runtime.

Tagged Releases

Tagged release URLs have the form<release_number>/shells/web-shell (the list of releases is here). A tagged release (with an older path due to a previous version of shell code) is v0.4.1.

Bleeding edge often works and is available on:


Arcs is developed with a recent version of Node (v10.0.0 at the time of this writing), in particular as we use new ES6 features. You can check our Travis config to see what version is used for automated build status. More recent versions should work, but if for example you see test errors on a version that's a full release later (ex. v11+) you may want to try rolling back to an earlier version. We welcome patches that will allow more recent versions to operate, ideally without requiring an upgrade to our current version.

Installing the easy way

  1. Run the setup script (MacOS, Linux)

    $ ./tools/setup
  2. That's it! (You can skip the next section.)

Installing from scratch

  1. Install nvm.

    As per the installation instructions, download and run the installation script directly in your terminal (yes, you read that correctly):

    $ curl -o- | bash

    If you're using zsh you may need to source ~/.nvm/ after this.

  2. Install node.

    $ nvm install 10
  3. If you need to update npm to a later version (our build checks for the minimum required version):

    $ npm install -g npm   # can use npm@6.3.0 to install a specific version
  4. Optional: install Bazel (required for building/running WebAssembly particles, optional if you only want to develop using JavaScript). See the ./tools/setup script for the correct version of Bazel to install. See the C++ wasm instructions for more info.

Installing within the Arcs project:

$ npm install
$ ./tools/sigh

npm install is required on a fresh checkout. After that it only needs to be re-run infrequently as new dependencies are included, and usually a build failure will be the signal for that.

Git Setup

You may also find it helpful to have sigh lint and type check your work locally before you commit it. To do this, you can setup git to run presubmit checks using:

$ git config core.hooksPath tools/hooks

Windows Installation Notes

  • Git for Windows is one of many Git options.
  • Consider using nvm-windows to allow more easily switching between Node versions.
  • As part of npm install you'll need to build fibers which uses node-gyp which in turn requires windows-build-tools. Follow the node-gyp Windows build instructions. If option 1 hangs or otherwise hits issues, you can try option 2. Note the Microsoft Build Tools 2015 can be downloaded separately from Visual Studio (and the links in the node-gyp documentation are stale), but you'll still need to do the npm config set msvs_version 2015 bit, and similar for Python if you install that manually per node-gyp option 2 instructions.
  • If you encounter errors due to spaces in your user name directory with either Git Bash or nvm, you may benefit from solutions described here and here.

Mac Installation Notes

  • When installing, if you run into SSL Cert verification errors, consider certifying Python 3.6 on Mac: /Applications/Python\ 3.6/Install\ Certificates.command (source)

Starting Arcs

After the full build (npm install && tools/sigh) run: (note that npm start will block, so you'll have to run the second command in a new shell):

$ npm start

Then open http://localhost:8786/shells/web-shell/ in a web browser (or, on MacOS, use open 'http://localhost:8786/shells/web-shell/).


Subcomponents have more detailed descriptions. Particularly the extensions also have individual installation steps.

Chrome Extension

See extension.

Chrome Developer Tools Extension

See devtools.


The simplest way to run tests is to let the targets do all the work. These commands will install all packages, run a build, start a background server, run all the tests, and kill the background server:

$ npm install
$ npm run test-with-start

There are additional targets provided to run subsets of those commands.

  • npm start: spins up a server (and blocks), serving on port 8786.
  • ./tools/sigh: run a subset of tests and build packed artifacts.
  • npm test: run all tests (using currently built artifacts) against an already-running server (assumed to be port 8786).
  • npm run test-no-web: run all non-web tests.

To run a specific Selenium test using Mocha's 'grep' capability:

  • In one terminal: npm start
  • In another: npm run test-wdio-shells -- --mochaOpts.grep 'regex'

This also works for unit tests: ./tools/sigh test --grep 'regex'. In addition, for unit tests you can run only a single test case by using it.only() instead of it(), or a single suite using describe.only() instead of describe().

WebAssembly tests

Test using Bazel (run from your repo root):

bazel test //src/wasm/... //src/tests/...

Debugging tests

If you see errors like

    at new RuntimeError (...\node_modules\webdriverio\build\lib\utils\ErrorHandler.js:144:12)
    at Request._callback (...\node_modules\webdriverio\build\lib\utils\RequestHandler.js:327:43)

It may indicate that chromedriver hasn't been installed completely. Run the install script:

node node_modules\chromedriver\install.js

Debugging unit tests in Chrome

You can attach the Chrome debugger to debug your unit tests using the --inspect flag:

./tools/sigh test --inspect

It will wait for you to attach your debugger before running the tests. Open [chrome://inspect] and look for the "inspect" button under the "Remote Target" heading. You can use Ctrl-P to open files (you may need to add the build folder to your workspace first). Hit "resume" to start running the unit tests.

Debugging Selenium Failures

Selenium failures are often easy to cause due to seemingly unrelated changes, and difficult to diagnose.

There are 2 main avenues to debug them in this system. The first is to have the browser run in a graphical manner (as opposed to the default headless configuration). The second is to actually debug the running selenium instance.

There are some debugging hints (code and configuration you can uncomment to make debugging easier) in test/specs/starter-test.js and test/wdio.conf.js marked with the phrase debug hint.

To activate a sane set of helpful debugging flags, there's a wdio-debug command line argument that you can pass in. This will run Chrome in a non-headless fashion, and will increase timeouts.

Through npm: npm run test-wdio-shells --wdio-debug=true (or npm test --wdio-debug=true). Directly through wdio: node_modules/.bin/wdio --wdio-debug=true shell/test/wdio.conf.js.

Webdriver takes screenshots of failures, which are saved to the ./shells/test/errorShots/ directory. When running on Travis, the screenshots are uploaded to the Arcs Webdriver Screenshots team drive.

Graphical (non-headless)

It may be easiest to see the problem in a browser window to diagnose it. Edit wdio.conf.js in the branch with failures, comment out the '--headless' option and increase the mocha timeout. In combination, these two changes will allow you to see what's happening on the screen, and will give you enough time to debug the situation.

arcs/shells> vi test/wdio.conf.js
arcs/shells> git diff test/wdio.conf.js
diff --git a/test/wdio.conf.js b/test/wdio.conf.js
index 0e36452..8ecf3d6 100644
--- a/test/wdio.conf.js
+++ b/test/wdio.conf.js
@@ -50,7 +50,7 @@ exports.config = {
       chromeOptions: {
         args: [
           // arcs note: comment this out to see the system running
-          '--headless'
+          // '--headless'
@@ -139,7 +139,7 @@ exports.config = {
   mochaOpts: {
     ui: 'bdd',
     // arcs note: increase this timeout for debugging
-    timeout: 20003
+    timeout: 2000003
   // =====

Then, in your test, you can add a breakpoint (via browser.debug();) to pause execution so you can debug in the browser. It may be worthwhile to add several browser.debug() invocations through your flow to trace execution (.exit will exit the debugger and continue execution of the test).

At that point you can open up DevTools in the browser to debug the current state, or inspect it visually. Some utilities (those in selenium-utils.js, including pierceShadows) have already been loaded.

There are also some commands available natively at that point, including .help and the browser variable (including methods such as browser.execute()).

Attaching a Debugger

To attach a debugger, uncomment the execArgv --inspect configuration option. It's likely that you'll still want to have increased the mochaTimeout and to be running graphically, so those are in the example as well:

arcs/shells> git diff test/wdio.conf.js
diff --git a/test/wdio.conf.js b/test/wdio.conf.js
index 0e36452..4240c0a 100644
--- a/test/wdio.conf.js
+++ b/test/wdio.conf.js
@@ -50,11 +50,12 @@ exports.config = {
       chromeOptions: {
         args: [
           // arcs note: comment this out to see the system running
-          '--headless'
+          // '--headless'
+  execArgv: ['--inspect'],
   // ===================
   // Test Configurations
@@ -139,7 +140,7 @@ exports.config = {
   mochaOpts: {
     ui: 'bdd',
     // arcs note: increase this timeout for debugging
-    timeout: 20003
+    timeout: 2000003
   // =====

When starting, you should see log item like debugger listening on ws:// as normally appears for node debugging. Passing the --inspect argument will also enable the V8 Inspector Integration which may be easier to use (to activate this, look for a node icon in a Chrome DevTools process).

Adding debugger; statements may be the easiest way to activate the debugger. Using browser.debug(); statements to pause execution to give you time to attach a debugger may be helpful as well.


Our release process is pretty minimal, but requires a few steps across the arcs and arcs-live repositories.

Our standard is to have the stable versions start with clean (empty) databases, but to continue a single mainline/unstable database.

  1. Decide what your new mainline and stable versions will be. For an example here, I'll use 0.3.5-alpha as the old mainline, 0.3.6-alpha as the new mainline, and 0.3.5 as the new stable version.

  2. In order to keep the mainline data roughly consistent, clone the data at the current firebase key to the new mainline release number. To do this, I used the firebase web interface to "Export JSON" for the current tree, and "Import JSON" to the new tree.

For example, clone from <snip>/database/arcs-storage/data/0_3_5-alpha to <snip>/database/arcs-storage/data/0_3_6-alpha.

If the web interface is read-only due to too many nodes, you can visit the new version's URL directly to Import JSON.

  1. Update the version in shell/apps/common/firebase-config.js to a reasonable stable version (in our example, 0.3.5). See #1114 for an example. Update the links (this file) to reflect this new version.

  2. Once the deploy is done to arcs-live, create a new release. Note that we remap the versions slightly between the two systems for legibility in different systems - a version of 0_3_5 (in firebase-config.js) becomes v0.3.5 (in the arcs-live repo).

  3. Update the version in shell/apps/common/firebase-config.js to the new mainline development version (perhaps using the -alpha suffix; in our example, 0.3.6-alpha). See #1155 for an example.

You can’t perform that action at this time.