forked from janmejay/tlb
-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathREADME.release
167 lines (109 loc) · 12.4 KB
/
README.release
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
Test Load Balancer (TLB)
========================
Basic Definition
----------------
TLB aims at splitting your test suite into a given number of mutually exclusive and collectively exhaustive units such that each unit can be executed in parallel. Assuming that tests are written independent of each other, which is a best practice in writing tests, they can be re-ordered and arranged in any fashion and TLB leverages this fact in split test suite into the given number of units and re-order the tests to, for instance, run tests that failed in last run, first(fail fast).
Balancer is meant to be hooked with your build script and test runner. This hookup ensures TLB gets appropriate callbacks when tests are about to be executed, so it can prune the list of tests to be executed to execute only a part of whole, and change test execution order etc.
In order to do this, TLB uses historical test run data from the TLB server(or equivalent).
For details, refer to the online documentation page at http://test-load-balancer.github.com
System Requirements
-------------------
Platform - Since TLB is written in Java, it is platform independent. Though we have tested it only on GNU/Linux, Windows and MacOS, it should work on any platform that is Java enabled.
Java - JRE/JDK 1.6 (We recommend using Sun(Oracle) Java, however, it should work as well with OpenJDK)
Memory - TLB balancer component should work with about 32MB of RAM for most setups.
Getting TLB
-----------
TLB can be downloaded from http://code.google.com/p/tlb/downloads/list
TLB is distributed as 'tarred + gziped' files(.tar.gz). Uncompressing the archive produces a directory containing the artifacts.
TLB is bundled in various combinations so as to allow users to download exactly what they need. Here is a short description of the contents of each such distributable.
Archive Name Contents
------------ --------
tlb-complete-XXX.tar.gz Has everything(all tlb artifacts and example projects bundled). If you are a new user or are unsure of what you want to go with, go with this. You do not need to download any of other packages if you pull this one.
tlb-java-XXX.tar.gz Contains TLB java support library and its dependencies. Dependencies are shipped in a directory named 'lib'. Java users will need to drop both tlb-java jar and its dependencies in build and test class-path(s).
tlb-server-XXX.tar.gz Contains TLB server, and 'shell-script'(for *nix) and 'bat-script'(for Windows) to manage the server process.
setup-examples-XXX.tar.gz Contains tiny projects that demonstrate TLB hookup in projects written using different languages and/or testing and build frameworks. This will be useful for people trying to setup TLB on their own project(s)/wanting to see TLB work before they set it up on their project.
To unarchive TLB distribution:
You can use "tar -zxvf tlb-YYY-XXXX.tar.gz" on *nix(GNU/Linux, Unix or MacOS). Windows users can unarchive the distribution using WinRAR, 7z or the Zip Utility(bundled with recent versions of Windows, the zip utility bundled with older versions may not work).
Building TLB from source
------------------------
TLB is a Java project that uses ant for building, ivy for dependency management and junit for tests.
Follow these steps to get TLB building locally
* Clone the code base
* Make sure you have:
** JDK 1.6
** ant 1.7 or above
** ant-junit libraries in the ant lib directory
* TLB uses ivy to manage dependencies. Hence, the build will need to be able to download all the dependent libraries from a maven repo.
* In the checkout directory, run ant. This will download all the deps (only the first time), compile and run all tests for all the modules and build the packages.
* Checkout the build.xml file to see all the build targets.
Artifacts: TLB(Archive Contents/Downloads)
------------------------------------------
tlb-complete
------------
server/
tlb-server-XXX.jar : Standalone TLB server jar file. This can be used to spin up the TLB server, which is a very lightweight restful http server.
server.sh and server.bat : Utility script to manage TLB server from the command line(for *nix and Windows respectively).
java/
tlb-java-XXX.jar : TLB Java support library(Java users would want to add this to their build and test classpath.
lib/ : Libraries TLB Java support library depends on. These jars need to be added to the build/test classpath as well. If the subject Java project already has dependency on a few of the libraries TLB depends on, they can be omitted(so TLB will .
alien/
tlb-alien-XXX.jar : (Matters only for people developing/maintaining TLB support libraries for other languages) TLB alien environment(non-java environment) support library. This is a standalone jar too. Jar invocation runs very lightweight http server. Alien language support library maintainers bundle this library, so as an end user you do not need to worry about this artifact.
examples/ : Has several tiny example projects made to demonstrate TLB in action, hooked up in projects written using different languages and/or testing and build frameworks. Check examples/README for details.
source/
tlb-XXX-src.jar : TLB source archive. Note: TLB is a multi-module project, to keep things simple for reference purposes we bundle all the module sources merged into one. While this is good for debugging and reference purposes, its not appropriate for contributing-to/patching TLB. Please use the upstream repository for patch work.
README : This file.
LICENSE : License file.
tlb-server
----------
tlb-server-XXX.jar : Standalone TLB server jar file. This can be used to spin up the TLB server, which is a very lightweight restful http server.
server.sh and server.bat : Utility script to manage TLB server from the command line(for *nix and Windows respectively).
README : This file.
LICENSE : License file.
tlb-java
--------
tlb-java-XXX.jar : TLB Java support library(Java users would want to add this to their build and test classpath.
lib/ : Libraries TLB Java support library depends on. These jars need to be added to the build/test classpath as well. If the subject Java project already has dependency on a few of the libraries TLB depends on, they can be omitted(so TLB will .
README : This file.
LICENSE : License file.
setup-example (some of the TLB artifacts are bundled in to meet example dependencies)
-------------
server/
tlb-server-XXX.jar : Standalone TLB server jar file. This can be used to spin up the TLB server, which is a very lightweight restful http server.
java/
tlb-java-XXX.jar : TLB Java support library(Java users would want to add this to their build and test classpath.
lib/ : Libraries TLB Java support library depends on. These jars need to be added to the build/test classpath as well. If the subject Java project already has dependency on a few of the libraries TLB depends on, they can be omitted(so TLB will .
examples/ : Has several tiny example projects made to demonstrate TLB in action, hooked up in projects written using different languages and/or testing and build frameworks. Check examples/README for details.
README : This file.
LICENSE : License file.
Note for Ruby users: Ruby example projects depend on the corresponding TLB gem being installed. For instance, you will need to 'gem install tlb-rspec2' before you can execute examples/rspec2_example specs.
If you have pulled down the tlb-complete archive, java libraries should be found under top-level-dir/java and server artifacts would be found in top-level-dir/server, as opposed to top-level-dir if you have pulled down tlb-java or tlb-server archive respectively.
Usage(Balancer)
---------------
Please ensure a suitable version of Java is installed. We highly recommend referring to 'Quick Start' page on TLB website. This page has typical build script fragments you can borrow, or refer to, while setting up 'load-balanced-test-runner' task in your build script(s).
If you are using TLB in a Java project, you can add the jars in this distribution to your test classpath. This means, you will have to copy tlb-java-XXXX.jar and other jars that tlb-java jar depends on(which are bundled alongwith, in the sub-directory named 'lib'), to your project's classpath.
For any other environments(for instance, Ruby), you only need to ensure java(the command) can be invoked at the console prompt(i.e. the command is available on PATH). No copying of jar(s) or any other scripts is necessary for Ruby support as tlb ruby-gems are self-sufficient and stand-alone.
Usage(Server)
-------------
To start the TLB server, execute: "./server.sh start"(on *nix) or "server.bat start"(on windows) from the directory extracted out of TLB archive(TLB download archive extracts to a directory named tlb-YYY-XXX(where XXX is the version number, and YYY is the type)).
Feel free to make changes to the respective scripts to tweak values TLB Server uses for exposed configuration variables. Please visit the Configuration Reference page on the TLB website(documentation section) to get detailed description of role and possible values for each of these environment variables.
Examples
--------
TLB team maintains a project called sample_projects that has several tiny projects(written in different languages using varity of testing and build frameworks), that are meant to demonstrate balancing/re-ordering and provide new users a working project to play with, before incorporating test-load-balancing in their own projects.
This is also acts as a good proving ground to play around with configuration variables and to understand the effect/implication of changing different parameters.
The tiny projects under this directory have test-cases that are executed by a helper script named 'run_balanced.sh' in a balanced fashion. The two primary things this helper script does are:
1. Starts the TLB server (Partitions need a server to post/pull data, this server started by the helper script is equivallent to the remote server in your real setup, the URL to which is provided to partitions). This server is started before the first partition starts and is terminated after the last partition finishes.
2. Executes a loop, which iterates as many times as the number of partitions. Each execution of this loop sets a different partition number and invokes a project sperific build task(i.e. an Ant task for ant_junit project and a Rake task for rspec2_example).
This script uses TLB to makes 2 partitions of these tests, and executes them serially(not parallely) on the local machine. In a real situation each one of these partitions will be executed on a different machine(or by a different process) "parallely". The helper script executes them serially only to demonstrate partitioning/re-ordering.
Sample projects directory is bundled along with every release for users to see and play with. Its usually a good idea to borrow build script configuration from the example project that matches your environment.
Useful Links
------------
http://test-load-balancer.github.com - Contains detailed documentation(TLB concepts, configuration reference, quick start and more), including documentation for the previous releases and other sub-projects(like tlb-ruby support project, etc).
http://github.com/test-load-balancer - The Github organization under which all the TLB projects are hosted.
http://github.com/test-load-balancer/sample_projects - Contains the sample implementation of TLB across different supported platforms and test/build frameworks. We tag it for every release we make.
http://code.google.com/p/tlb/issues - TLB issue tracker. Please use this page to report any bugs or submit feature requests/enhancements etc.
License
-------
TLB is a BSD licensed software.
Contact Us
----------
TLB development team can be reached at '[email protected]'. Please check http://test-load-balancer.github.com/contact_us.html for details.