Technical description

Mercurial integration

Meliora Testlab can be integrated with a Mercurial Version Control System to track links between your changesets, issues, and requirements.

  • How it works

    A Version Control System is a repository where the developers commit and push changes to be stored and versioned during the development. The changes are bundled as sets of changes (changesets) and when committed, are stored with a commit message explaining the changes included in the changeset.

    When a developer pushes changes to the repository, (s)he can include references to Testlab’s issues and requirements to the commit message. The repository then sends the information of the changeset to Testlab and the changeset information is stored to Testlab project and linked to related issues and/or requirements. When viewed through Testlab’s user interface, you can then inspect which changesets are related to these assets in your VCS repository. You can also – if properly set up – click and navigate via the changeset to dig deeper into the changes included in the changeset.

    With this workflow, in the Testlab project, you can

    • track which changes (in your repository) are related to which issues (in your Testlab project),
    • mark related issues resolved and close related issues through commit messages,
    • track which changes are related to which requirements and
    • easily view the details about changes.

    This enables you to better collaborate with your programmers and testers and have changesets as part of your testing project for future reference.

  • How to get started

    To set up the integration the following steps are needed:

    1. Set up an API key to your Testlab (if it is not yet set up),
    2. configure a hook script to your VCS repository on your VCS server,
    3. in the Testlab project, in project’s “Integrations” tab, select Mercurial as a “Version control” and configure options as preferred,
    4. and optionally,
      1. configure web access component to your repository to inspect changeset details via your browser and
      2. in the Testlab project, configure the URL address for your repository.

    The detailed instructions for each step follow.

     

    Setup an API key

    For the VCS system to be able to push changeset information to Testlab, an API key must be configured to your Testlab instance. To configure an API key, log into your Testlab as an administrator and go to Testlab > Manage company… > API keys and add a new key. Please, take note of your API key when you register one as the key is hash encoded to the database with no way of recovering it after saving your changes. An API key is basically a secret (password) the VCS system uses to authenticate to your Testlab.

     

    Configure the hook script

    For the integration to work, the VCS system needs to be set up with a hook script. A hook in VCS is a script that gets executed when some set operation in the repository occurs (such as push, commit, update, …). As your VCS is of distributed type and you are working as a team, you most likely are pushing your changes to a so-called central repository. For this, you should set up an “incoming” hook which gets triggered once for each changeset that is brought into the repository from elsewhere (pushed by your developers). For testing, you could also use a “commit” hook but keep in mind that then the hook gets executed once per your commit in your local repository only. You can read more about Mercurial’s hooks here.

    Configure the hook script with parameters

    To set up the hook script, download the pre-templated hook script hg_testlab_hook.zip. Unzip the archive (it is archived to make sure you can download the file) and you will end up with a bash-script capable of posting the results to Testlab.

    At the start of the script file, edit the following values:

    const REPOSITORY_ID = '';
const TESTLAB_COMPANY_ID = 'your company id';
const TESTLAB_APIKEY = 'your cryptical api key';
const TESTLAB_PROJECT = 'your Testlab project prefix';
// optional for on-premise Testlab installs:
const TESTLAB_API_URL = '...';
//const __DEBUG_FILE = '/tmp/testlab_hg_hook_debug.log';
    • REPOSITORY_ID: Enter a short descriptive name to your repository. This identifier is shown as ID of the repository for Testlab users (and optionally, it is used to reference the repository when configuring web access URLs for the repository). You can also leave this value as blank and if so, the value is automatically set as the basename of your repository folder (if your repository is in /some/path/myrepo, the REPOSITORY_ID value gets set as “myrepo”).
    • If you are using Meliora Testlab as a Service:
      • TESTLAB_COMPANY_ID: The virtual host domain you are using to access Testlab (for example, if you are accessing Testlab with https://somecompany.melioratestlab.com, set TESTLAB_COMPANY_ID as “somecompany”).
      • TESTLAB_APIKEY: The API key you have set up in your Testlab instance.
      • TESTLAB_PROJECT: The prefix identifier of the Testlab project you want to push the changesets to.
    • If you are using Meliora Testlab as an on-premise install:
      • TESTLAB_COMPANY_ID: Leave the value as ‘company’.
      • TESTLAB_APIKEY: The API key you have set up in your Testlab instance.
      • TESTLAB_PROJECT: The prefix identifier of the Testlab project you want to push the changesets to.
      • TESTLAB_API_URL: The HTTP (or HTTPS) address of your Testlab server with /api/vcs/hg appended (for example “https://ourtestlab.ourdomain.com/api/vcs/hg”)
    • If you wish for the script to write debug logging to a file, you can comment out the __DEBUG_FILE parameter and optionally, change the name of the file the log is written to. This is the first thing to do if you are having any trouble using this script.
    Install the tools and dependencies needed for the script

    The script uses Node.js runtime for the call that is made to Testlab. For this, you should install Node.js runtime and needed Node.js components.

    1. Install Node.js runtime on the server, if needed. You can download one from here or preferably, install it via a package manager on your system.
    2. Install the needed node.js modules by running
    # npm install -g node-rest-client

    Note: If you have problems with Node runtime not finding your (globally) installed modules by giving an error “Cannot find module: node-rest-client” or similar, you should make sure your NODE_PATH environment variable points to a correct directory. Node uses this directory to find installed modules.

    Set up the hook to your repository
    1. Log in to your VCS server and in the file system, go to the root directory of the repository you wish to push the changes from.
    2. Copy the configured hook script to the .hg/ directory under the root directory of the repository.
    3. Edit the .hg/hgrc file in the repository directory and add/edit the following to this file:
    [hooks]
incoming = node .hg/hg_testlab_hook.sh

    Note: If your Node.js installation has trouble finding your (possibly globally) installed modules, you can explicitly set the path for searched modules. For example, you could set up your hook as follows:

    [hooks]
incoming = export NODE_PATH=/usr/lib/node_modules;node .hg/hg_testlab_hook.sh

    Configure Testlab project’s “Version control” integration

    1. Log in to your Testlab project and choose Testlab > Manage projects… > Your project > Integrations
    2. Choose “Mercurial” as your Version control system of choice and set the options:
      • Allow resolving of issues through commit messages?
        If set, committers may resolve issues with special commit messages (See “Linking changes to Testlab project assets” below).
      • Allow closing of issues through commit messages?
        If set, committers may close issues with special commit messages (See “Linking changes to Testlab project assets” below).
      • Repository URLs
        Sets the (optional) URL-addresses for web-published repositories (See below).

     

    Optional: Configure a web access component for your repository

    If you wish to be able to inspect your changesets via your Testlab project, you should have (or set up if missing) some kind of web access to your repository. This means that your repository should be browseable with a browser by your users (“HTTP/HTTPS mechanism”).

    Installing such component is beyond the scope of this manual, but with Mercurial, it is easy to set up with “hg serve” or “hgweb”. You can read more about your options on publishing your repositories at

    • https://www.mercurial-scm.org/wiki/PublishingRepositories
    • https://www.mercurial-scm.org/wiki/hgserve
    Configure the URL addresses to your Testlab project

    If you have a web browser browsable repository, you should configure the URL address of it to your Testlab project. To do this,

    1. Log in to your Testlab project and choose Testlab > Manage projects… > Your project > Integrations
    2. Choose “Mercurial” as your Version control system of choice and for each repository you’ve set up the hook script for, configure the full repository browser URL address. In the URL address, you should use $ID as a placeholder for the changeset identifier. The left-hand side “Repository ID” should match the REPOSITORY_ID value you have configured to your hook script earlier. For example, if you would be running “hg serve” at your “vcsserver.domain.com” server, the Repository browser URL should be something like “http://vcsserver.domain.com:8000/rev/$ID“.

     

    The integration should now be set up. You should read on for information on how to format the commit messages to actually link and store the changeset links to your Testlab project.

  • Linking changes to Testlab project assets

    When a developer pushes a changeset to the repository, it holds commit messages which describe the changes included. When the integration is enabled, the commit messages are inspected for special keywords to indicate how to link the changesets to the assets in the Testlab project. The table below lists all variations for keywords supported.

    Keyword(s), with example(s) Description
    refs #ISSUEID, issue #ISSUEID

    Examples:

    Partially fixes issue #TLABDEMO-6, refs #TLABDEMO-2
    		 Stores the changeset and links it to an issue with ID “ISSUEID”.

    The example links the changeset to two issues, TLABDEMO-6 and TLABDEMO-2.
     fixes #ISSUEID, fix #ISSUEID

    Fixes #TLABDEMO-5, also fix #TLABDEMO-4
    		 Stores the changeset and

    1. links it to an issue with ID “ISSUEID” and
    2. marks the issue as resolved.

    The example links the changeset to two issues, TLABDEMO-5 and TLABDEMO-4, and marks them as resolved.
    closes #ISSUEID, close #ISSUEID

    - closes #TLABDEMO-2
- also close #TLABDEMO-3
    		 Stores the changeset and

    1. links it to an issue with ID “ISSUEID” and
    2. closes the issue.

    The example links the changeset to two issues, TLABDEMO-2 and TLABDEMO-3, and closes these issues.
    req #REQID, requirement #REQID, impl #REQID, implements #REQID

    - impl #US2.1
- also implements #US2.2
- req #US3.1 needs clarifications
    		 Stores the changeset and links it to a requirement with ID “REQID”.

    The example links the changeset to three requirements, US2.1, US2.2 and US3.1.

     

  • Changesets in Testlab project

    To inspect linked changesets in your Testlab project,

    • for issues, open up an issue and choose the “Version control” tab and
    • for requirements, go to Requirements view in your Testlab project, select a requirement and choose the “Version control” tab.

    If you have configured web addresses for your repositories, the view also has appropriate controls in place to open up the specific revisions in your web-published repository.