If the LabKey Server team has provided you a Subversion account with read/write permission, you can check in changes that you make to the LabKey Server source. (Note that the public configuration described on the
LabKey Server version control documentation page is a read-only account.) Before you check in any changes, you must make sure that your code builds, that it runs as expected, and that it passes the relevant automated tests.
Update and Perform a Clean Build
Before you run any tests, follow these steps to ensure that you are able to build with the latest sources:
- Stop your development instance of Tomcat if it is running.
- From a command prompt, navigate to <labkey-home>/server
- Run the gradlew cleanBuild build task to delete existing build information.
- From your <labkey-home> directory (the root directory of your LabKey Server enlistment), use the svn update command to update your enlistment with the latest changes made by other developers.
- Verify that any merged files have merged correctly.
- Resolve any conflicts within files that have been modified both by you and by another developer.
- Run the gradlew deployApp target to build the latest sources from scratch.
Run the Test Suite(s)
LabKey maintains automated tests that verify most areas of the product. These tests use the
Selenium Remote Control test harness to exercise and verify server functionality by automating the browser. LabKey develops and runs all tests using the most recent versions of Chrome and Firefox supported by Selenium, which usually lags the most recent public browser release. Thus, Firefox
Extended Support Release (ESR)
v45 is recommended.
Newer versions of Firefox are not currently supported. You can have multiple versions of Firefox installed, as long as you specify the path to Firefox when you run the tests. For example:
gradlew :server:test:uiTest -Psuite=DRT -Pselenium.browser.path="c:\Program Files\Mozilla Firefox 45\firefox.exe"
LabKey currently maintains three test suites:
- Developer Regression Test (DRT): a quick (< 10 minutes) suite that developers run before every commit that touches core server code
- Build Verification Test (BVT): a longer (up to an hour) suite that our TeamCity-based server farm runs automatically after every commit
- Daily Test: an additional suite of tests that TeamCity runs once a night
If you modify the core server code, at a minimum, you need to run the DRT; running the BVT, the daily suite, or individual tests may also be helpful to verify your changes.
If you modify only custom modules, you should run their corresponding automated tests, as well as the JUnitTest which runs a variety of unit and integration tests, including DB schema validation.
To run the DRT, follow these steps:
- Start your development instance of Tomcat.
- From a command prompt, navigate to <labkey-home>/server/test
- Run the gradlew :server:test:uiTest -Psuite=DRT task. (Add -PhaltOnError=false to continue running if a test fails.)
- When prompted, enter the user name and password for an administrator account on your local development installation of LabKey Server.
The test targets you can use include:
- gradlew :server:test:uiTest -Psuite=DRT: Compile and run the DRT suite
- gradlew :server:test:uiTest -Psuite=BVT: Compile and run the BVT suite
- gradlew :server:test:uiTest -Psuite=issues: Compile and run tests for the issues module
- gradlew :server:test:uiTest -Ptest=JUnitTest: Compile and run just the JUnitTest
- gradlew :server:test setPassword: Change your saved password. This target sets your login information in your netrc file (<home>/.netrc -or- <home>_netrc)
- gradlew :server:test tasks: Display instructions and additional options
Test Failures
If a test fails, you'll see error information output to the command prompt, including the nature of the error, the point in the test where it occurred, and the name of an HTML file and a PNG file, written to the <labkey-home>/server/test/build/logs directory, which can be viewed to see the state of the browser at the time the test failed.
A helpful resource:
Java Debugging Tips
Modifying the Test Suites
You can add to or modify existing tests and create new tests. To build the tests, use the
gradlew :server:test:build target. To run a particular test, regardless of suite, use
-Ptest (see above)
To edit an existing test, locate the test class beneath the <labkey-home>/server/test/src directory or in the test/src directory of the module that defines it.
To create a new test, extend org.labkey.test.BaseWebDriverTest and annotate it with org.junit.experimental.categories.Category.
Make sure that you carefully test any changes you make to the tests before checking them in.
Checking In Code Changes
Once you pass the tests successfully, you can check in your code. Make sure that you have updated your enlistment to include any recent changes checked in by other developers. To determine which files to check in, use the
svn commit command. This command displays a list of the files that you have modified, which you can compare to the repository version. Be sure to provide a log message with your check-in so that other developers can easily ascertain what you have changed. An automated email describing your check-in is immediately sent to all who have access to the LabKey Server source project.
After you check in, TeamCity will build the complete sources and run the full BVT on all of the supported databases as an independent verification. You'll receive another email from the automated system letting you know whether the independent verification passed or failed. We request that you remain available by email from the time you check in until you receive the email confirming that the automated build and test suite has passed successfully, so that if there is a problem with your check-in, you can revert your change or check in a fix and minimize the amount of time that others are blocked.
Related Topics
