Ti-Debugger

Ti-Debugger is a fork of TiShadow by David Bankier. https://github.com/dbankier

This project was modified for my personal needs.

Getting Started

Ti-Debugger NPM Package

Ti-Debugger is built on node.js and is required.

Ti-Debugger can be installed via npm using the following command:

$ npm install -g tidebugger

PLEASE NOTE: The package installs titanium hooks in the post install. If you install with sudo and get the error Unable to write config file... use the following command:

$ sudo npm install -g tidebugger --unsafe-perm

Or if you want to use the master version directly from GitHub:

  npm install -g dbankier/Ti-Debugger

NEW DUMMY'S PATH: Ti-Debugger Express

You can do a lot with Ti-Debugger. Keep reading this README to find out more. But if it is all too much at the moment and you just want to use it for live reload you can do the following.

During install a titanium cli plugin/hook was installed for you. From your project you can just use the following command:

  titanium build -p android -T device --tidebugger

This will launch your app in the simulator and reload with any code/style/localisation changes.

Under the hood it:

1. starts the tidebugger server - tidebugger server
2. launches an appified version of your app - tidebugger appify (with extra flags)
3. watches your code and push on any changes - tidebugger @ run --update

MAC: If you get the error EMFILE: Too many opened files., this is because of your system's max opened file limit. For OSX the default is very low (256). Increase your limit temporarily with ulimit -n 8192, the number being the new max limit.

Ti-Debugger App

To create a new titanium project use the following command:

  tidebugger app -d [destination folder]

e.g.

  mkdir ~/tidebuggerapp
  tidebugger app -d ~/tidebuggerapp

NOTE: In general upgrade the server side and app at the same time (using the tidebugger app command).

You can upgrade an existing tidebugger app using the --upgrade flag.

Start the Ti-Debugger Server

The server can be started by typing the following command:

  tidebugger server

The following options are available:

    -h, --help             output usage information
    -p, --port <port>      server port
    -l, --long-polling     force long polling
    -i, --internal-ip <internal-ip>  internal ip to bind to
    -s, --screenshot-path <screenshot-path>  path to save screenshot (defaults to /tmp)
    -z, --manage-versions  manage and automatically update bundles

If --manage-versions is enabled, then bundle versions are tracked and devices that connect with an older version will automatically be updated. When using this mode, you can use the tidebugger deploy command to send a new bundle to the server without pushing it to connected devices.

Remote Server Mode and Private Rooms

The Ti-Debugger Server supports remote hosting with configurable http ports. It also allow for private "rooms" (much like chat rooms) so that the Ti-Debugger server can be shared.

The tidebugger log command is available to tail remote server logs (in the default or selected room).

The tidebugger config command is available to set the default host, port and room for all the relevant command below.

Start the Ti-Debugger App

Once the server is running launch the app. For example, to launch the app in the iPhone simulator using the Titanium CLI:

  cd ~/tidebuggerapp
  titanium build -p iphone

From the app just enter the ip address or hostname of the computer running the server and hit connect. (There are also more advanced connection settings that can be used for remote server connections.)

What you can do with Ti-Debugger

Full Application Deployment

Go to the root folder of your project and enter the following command to deploy an app:

  tidebugger run

If the app has been deployed and you want to push minor updates, use the following command:

  tidebugger run --update

Here are full list of options:

    -h, --help             output usage information
    -u, --update           Only send recently changed files
    -a, --patch            patch updated files without causing app restart
    -l, --locale <locale>  set the locale in in the Ti-Debugger app
    -j, --jshint           analyse code with JSHint
    -t, --tail-logs        tail server logs on deploy
    -o, --host <host>      server host name / ip address
    -p, --port <port>      server port
    -r, --room <room>      server room

The app is then cached on the device. If need to clear the cache, use the following command:

  tidebugger clear

Some notes and limitations

• Ti.include is partially supported and will work if included with the full path i.e. slash leading.
• Only files in the Resources directory will be sent to the device using Ti-Debugger. That said, localisation files are supported. (see options above).
• Native modules can be supported if built into the Ti-Debugger app first. (I.e., add them to the tiapp.xml of the Ti-Debugger app.)
• Custom fonts will be loaded if placed in the Resources/fonts directory for iOS only.
• If there any errors about a Titanium SDK command not being found, add them to the Includes.js files and clean and build the Ti-Debugger app. (I will gradually be adding commands.)
• Any Ti.API logs will be redirected to the server logs and webpage.

Testing / Assertions

Include your specs in the spec path of your project. Ensure the files are ending in _spec.js. (Note: simply write the spec without any including/requiring the jasmine library.)

To execute the tests enter the following command:

  tidebugger spec

Here are a full list of options:

    -h, --help             output usage information
    -u, --update           Only send recently changed files
    -l, --locale <locale>  Set the locale in in the Ti-Debugger app
    -o, --host <host>      server host name / ip address
    -p, --port <port>      server port
    -r, --room <room>      server room
    -t, --type <type>      testing library
    -j, --jshint           analyse code with JSHint
    -x, --junit-xml        output report as JUnit XML

NEW: You can now select the testing library to use jasmine, mocha-should or mocha-chai. The default library is jasmine to change that use, e.g. tidebugger config -t mocha-should.

Alternatively (yet not preferred)

Ti-Debugger also supports the use of assertions and the results are returned either to the browser or server logs.

For example:

    assert.isNumber(6, "Testing if 6 is a number");
    assert.isArray([1,2,3,4], "Testing if it is an array");

The following assertion are supported: 'equal', 'strictEqual', 'deepEqual', 'isTrue', 'isFalse', 'isEmpty', 'isElement', 'isArray','isObject', 'isArguments', 'isFunction', 'isString', 'isNumber', 'isFinite', 'isBoolean', 'isDate', 'isRegExp', 'isNaN', 'isNull', 'isUndefined', 'lengthOf', 'match', 'has'

Also the equivalent not assertions are available as well, e.g. 'notEqual', 'isNotString', 'isNotNumber', etc.

Configurable Localisation

Ti-Debugger supports dynamic localisation. You can also chose the locale you wish to use when launching your app/tests. Simply add the two-letter language code to your command. For example:

  tidebugger run --locale es
  tidebugger spec --locale nl

Ti-Debugger REPL

The Ti-Debugger REPL is available and evaluates commands in a persistent sand-boxed context.

To Launch the REPL enter the following command:

  tidebugger repl

With the following options:

    -h, --help         output usage information
    -o, --host <host>  server host name / ip address
    -p, --port <port>  server port
    -r, --room <room>  server room

launchApp(appName), closeApp() and clearCache() methods available to interact with apps cached in the Ti-Debugger app.

require(), Ti.include() and assets are relative the running app inside the Ti-Debugger app.

Spies

You can add spies on objects so that you can modify them from the repl at run time. In your code add the following command: addSpy(name, object). This can be included as a comment, eg: //addSpy("mywindow",win) which will be uncommented when pushed. To get the object, simply use, e.g. getSpy("mywindow") from the repl.

Screenshots

You can capture screenshots of all connected devices using the following command:

  $ tidebugger screenshot

The screenshots will be saved in png format in the /tmp directory or the path configured using the --screenshot-path flag when starting the server.

Screencast mode

Instead of saving the screenshots you can stream them to the browser. Use the following command:

  $ tidebugger screenshot --screencast 1000 --scale 0.1

In the above example a screenshot is sent every 1000ms and scales the images to 10% of their height/width. Go to: http://localhost:3000/screencast to view the screencast.

Code Snippets Via Webpage

Enter the following address in a browser window:

    http://localhost:3000/

Coding from the webpage works much like the REPL and variables are stored in a sand-boxed context. See the next section.

Ti-Debugger Appify

The tidebugger appify command can be used to create a stand-alone app that is integrated with Ti-Debugger. It automatically launches the contained tidebugger bundle and connects to a pre-configured server. The allows connecting to the deployed app via the repl and/or push upgrades.

  Usage: appify [options]

  Options:

    -h, --help                output usage information
    -d, --destination <path>  target path for generated project
    -o, --host <host>         set server host name / ip address
    -p, --port <port>         set server port
    -r, --room <room>         set server room