Quick Titanium previews across devices
npm install tishadow
|13||downloads in the last day|
|117||downloads in the last week|
|410||downloads in the last month|
|Version||2.5.2 last updated 20 days ago|
|License||Apache Public License v2|
|Dependencies (20)||ticonfig, jade, socket.io, socket.io-client, colors, commander, pkginfo, jshint, wrench, underscore, archiver, express, lazystream, form-data, uglify-js, mocha, tiapp, gaze, glob, async|
|Starred by||joliva, xtopher|
TiShadow provides Titanium developers the ability to deploy apps, run tests or execute code snippets live across all running iOS and Android devices.
There are three parts to TiShadow: the TiShadow server, TiShadow app and TiShadow CLI which are all need.
Have a look at this presentation (July 2012) given at the TiLondon meetup for a look at most of what you can do with TiShadow. (Outdated)
Go to the new project website
TiShadow NPM Package
TiShadow is built on node.js and is required.
TiShadow can be installed via npm using the following command:
sudo npm install -g tishadow
Or if you want to use the master version directly from GitHub:
sudo npm install -g dbankier/TiShadow
NEW DUMMY'S PATH: TiShadow Express
You can do a lot with TiShadow. 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 --shadow
This will launch your app in the simulator and reload with any code/style/localisation changes.
Under the hood it:
- starts the tishadow server -
- launches an appified version of your app -
tishadow appify(with extra flags)
- watches your code and push on any changes -
tishadow @ 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.
To create a new titanium project use the following command:
tishadow app -d [destination folder]
mkdir ~/tishadowapp tishadow app -d ~/tishadowapp
NOTE: In general upgrade the server side and app at
the same time (using the
tishadow app command).
You can upgrade an existing tishadow app using the
Start the TiShadow Server
The server can be started by typing the following command:
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
--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
tishadow deploy command
to send a new bundle to the server without pushing it to connected
Remote Server Mode and Private Rooms
The TiShadow Server supports remote hosting with configurable http ports. It also allow for private "rooms" (much like chat rooms) so that the TiShadow server can be shared.
tishadow log command is
available to tail remote server logs (in the default or selected room).
tishadow config command is available to set the default host, port
and room for all the relevant command below.
Start the TiShadow App
Once the server is running launch the app. For example, to launch the app in the iPhone simulator using the Titanium CLI:
cd ~/tishadowapp 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 TiShadow
Full Application Deployment
Go to the root folder of your project and enter the following command to deploy an app:
If the app has been deployed and you want to push minor updates, use the following command:
tishadow 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 TiShadow 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:
Some notes and limitations
Ti.includeis 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 TiShadow. That said, localisation files are supported. (see options above).
- Native modules can be supported if built into the TiShadow app first. (I.e., add them to the tiapp.xml of the TiShadow app.)
- Custom fonts will be loaded if placed in the
Resources/fontsdirectory 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 TiShadow 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:
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 TiShadow 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
The default library is
jasmine to change that use, e.g.
tishadow config -t mocha-should.
The test results will be returned to the server/cli output:
See the included example project or this blog post.
Alternatively (yet not preferred)
TiShadow also supports the use of assertions and the results are returned either to the browser or server logs.
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.
TiShadow 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:
tishadow run --locale es tishadow spec --locale nl
The TiShadow REPL is available and evaluates commands in a persistent sand-boxed context.
To Launch the REPL enter the following command:
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
clearCache() methods available
to interact with apps cached in the TiShadow app.
Ti.include() and assets are relative the running app
inside the TiShadow app.
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.
For Alloy, since comments are removed at compile time you can use the
following alloy.jmk to
automatically inject spies on the
$object in your controllers, naming
the spy with the file's name.
You can capture screenshots of all connected devices using the following command:
$ tishadow 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.
Instead of saving the screenshots you can stream them to the browser. Use the following command:
$ tishadow 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.
http://localhost:3000/screencast to view the screencast.
Code Snippets Via Webpage
Enter the following address in a browser window:
In the editor you can enter code and press Command+s to deploy the code snippet to all connected devices. Have a look at the demo video.
Coding from the webpage works much like the REPL and variables are stored in a sand-boxed context. See the next section.
tishadow appify command can be used to create a
stand-alone app that is integrated with TiShadow. It automatically
launches the contained tishadow bundle and connects to a pre-configured
server. The allows connecting to the deployed app via the repl and/or
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
See the following blog post.
Launch From Web
Currently only working on iOS
You can also use TiShadow to bundle an app and launch it from a web
page. Use the command
tishadow bundle to bundle the app for a
TiShadow distribution. Then include a link to the bundle in your webpage
using the following format, e.g. :
Tapping on the link from your browser should launch the app in TiShadow.
Those using vim/gvim/mvim for development might want to add these shortcuts (or similar) to the .vimrc/.gvimrc files. It add the shortcuts, F6 to save and do a tishadow update, and Shift+F6 to save and perform a full tishadow deploy:
:map <F6> <Esc>:w<CR>:!tishadow run --update<CR>a :imap <F6> <Esc>:w<CR>:!tishadow run --update<CR>a :map <S-F6> <Esc>:w<CR>:!tishadow run<CR>a :imap <S-F6> <Esc>:w<CR>:!tishadow run<CR>a
The server code uses the following and are included:
The app is built using Appcelerator's Titanium.
Third Party Modules
Copyright 2012 jordi domenech firstname.lastname@example.org Apache License, Version 2.0
Now using ti.compression: titanium_modules
project : TiShadow repo age : 1 year, 10 months active : 176 days commits : 393 files : 197 authors : 303 David Bankier 77.1% 42 dbankier 10.7% 35 Fokke Zandbergen 8.9% 2 noughts 0.5% 1 Lee, JongEun 0.3% 1 Clément Blanco 0.3% 1 Pedro Palmero 0.3% 1 Timan Rebel 0.3% 1 astronaughts 0.3% 1 iskugor 0.3% 1 jsjant 0.3% 1 Luis Cruz 0.3% 1 Hugh Cannon 0.3% 1 Ivan Skugor 0.3% 1 Jeff Bonnes 0.3%