The testbuilder module implements a fully-functional automated system for downloading, building, and running automated test suites on software source distributions. It has a web based interface, utilising sconeserver's http module, as well as a standard sconescript interface.
Using testbuilder via the web interface.
Before you start a test build, you must first define a profile. A profile specifies exactly what steps you want the test build to perform. Profiles can be saved and reused, so you can start another test build sometime in the future with exactly the same settings, and you can list all the test builds that have been performed with a particular profile. You may find there are already some profiles defined. These are listed under the "Profiles" heading on the left of the page.
To create a new profile, enter a suitable name in the box on the left (under the "Profiles" heading), and click the "New" button. The profile should appear in the list on the left, and the profile configuration should be displayed. Note: the name of the profile may contain only letters, numbers and underscores, and must start with a letter.
See the BuildProfile page for details on how to configure a build profile.
Saving and removing profiles
The "Save profile" and "Remove profile" buttons do exactly what they say. Saved profiles will be remembered even if the machine is powered down. Note that removing a profile will not remove any builds assoicated with it.
Starting a build
Pressing the "Start build" button will cause a build to be created and submitted to the system using the current profile.
when a build is submitted, it is put on the end of a queue to be run by the testbuilder. The amount of time it has to wait to be run will depend on how many other builds are queued ahead of it, and how many builds the system is allowed to run simultaneously (see later section on configuration).
When each step of the build is completed, the exitcode of the command is checked. The status is updated accordingly and will be visible on the web page. A nonzero exitcode is taken as a failure, and any failing step will cause the test build as a whole to fail, stopping at that point. Only when all the steps of the test build pass will the test build be marked as passed.
If the build is aborted, either manually by pushing the "Abort build" button, or if the system is shutdown while the build is running, the build step that was running will be marked as "ABORTED", as will the build as a whole. Any previously passed steps will still be visible. Any unstarted builds that are in existance when the system shuts down will be rescheduled when the system is restarted.
Once the build has started running, it is possible to browse the files in the build directory using the web interface by clicking on "View files". It is also possible to view the log files that are output for each build step once it has started running. Using the "View" options on the left, it is possible to list all builds in a particular state.
In addition to the standard module interface, it also has the following:
|max_running||Int||The maximum number of simultaneous test builds|
|source_methods||List of SourceMethod||The available source methods|
|profiles||List of String||The available build profiles|
|buildstats||List of BuildStat||Information on all current builds|
- add ( profile_name : String ) [Trusted]
- Add a new test builder profile.
- remove ( profile_name : String ) [Trusted]
- Remove a test builder profile.
- submit_build ( profile_name : String ) : String [Trusted]
- Submit a test build using the specified profile. Returns the ID of the newly created build, if successful.
- abort_build ( build_id : String ) [Trusted]
- Abort a test build. If the build is running, any currently executing steps are immediately terminated. If the build is running or is unstarted, it is marked as aborted. If it has already finished running, nothing is done.
- remove_build ( build_id : String ) [Trusted]
- Remove a test build along with all associated files. If the build is currently running, it is first aborted as above.
- set_dir ( path : String ) [Trusted]
- Sets the directory for the testbuilder system to use. This is where saved profiles, scripts and builds are stored.
- set_max_running ( num : Int ) [Trusted]
- Sets the maximum number of builds that will be permitted to run simultaneously. This defaults to 1, i.e. builds are run one at a time.
- set_build_user ( user_name : String ) [Trusted]
- Sets the user to run the test builds as. This defaults to "nobody", but it is a good idea to have a dedicated user and group for this purpose, for security reasons.
- add_source_method ( method_name : String, method_description : String ) [Trusted]
- Registers a source method with the system. The method-name should correspond to a script in the build_dir/scripts/ directory. Registered methods will appear in the option list on the web interface.
- load_profiles ( ) [Trusted]
- Load any previously saved profiles from disk.
- save_profiles ( ) [Trusted]
- Save all currently defined profiles to disk.
- start ( ) [Trusted]
- Starts the testbuilder module's build scheduler.
- stop ( ) [Trusted]
- Stops the testbuilder module's build scheduler.