CI Build ID environment variables by provider (Test Automation)

Why This Matters

In test automation, setting Continuous Integration (CI) Build ID environment variables is an essential practice that ensures traceability and repeatability of tests across different builds and environments. By associating each build with a unique identifier, you can easily reproduce issues, track changes, and maintain consistent results. This guide will walk you through the process of setting CI Build ID environment variables using JavaScript for popular test automation tools like Selenium, Cypress, and Playwright.

The Importance of CI Build ID Environment Variables

• Traceability: By tracking each build with a unique identifier, it becomes easier to reproduce issues that arise during testing. This helps developers identify the root cause of problems more quickly and address them effectively.
• Repeatability: Consistently setting the same environment variables across different builds ensures that test results are comparable and reproducible. This helps maintain a high level of confidence in your test automation suite.
• Change tracking: With CI Build IDs, you can easily track changes made to your test automation codebase over time. This is particularly useful when collaborating with other team members or maintaining long-term projects.

Prerequisites

Before diving into the core concept, ensure you have:

• A basic understanding of JavaScript programming language concepts such as variables, functions, and control structures.
• Familiarity with test automation tools like Selenium, Cypress, or Playwright, including their APIs and how to write tests using these frameworks.
• Selenium: Learn more about Selenium WebDriver at
• Cypress: Check out the official documentation for Cypress at
• Playwright: Visit the Playwright documentation to learn more at
• Knowledge about Continuous Integration (CI) platforms like Jenkins, GitLab CI/CD, CircleCI, or Bitbucket Pipelines, understanding the basic workflow and configuration files.
• Jenkins: Familiarize yourself with Jenkins at
• GitLab CI/CD: Learn more about GitLab CI/CD at
• CircleCI: Visit the CircleCI documentation to learn more at
• Bitbucket Pipelines: Check out the official documentation for Bitbucket Pipelines at

Core Concept

To set CI Build ID environment variables, we'll focus on three key aspects:

1. Understanding the CI system: Each CI platform provides a way to define and manage environment variables. For example, in Jenkins, you can create global or project-specific environment variables, while GitLab allows defining variables within .gitlab-ci.yml files. Familiarize yourself with the specific CI system you are using and its documentation to learn how to set environment variables.

1. Setting Build ID variable: The Build ID is typically a unique identifier generated by the CI system for each build. You can access this value in your test scripts to set an environment variable with the same name. Depending on the CI system, you might find different ways to obtain the Build ID, such as using predefined variables like $CI_PIPELINE_ID or $CI_BUILD_ID in GitLab CI/CD, or accessing environment variables set within your CI configuration.

1. Using the environment variable in tests: Once you've set the environment variable, you can use it in your test automation scripts to log or store the Build ID along with test results. This will help you trace specific builds and their associated test results, making it easier to reproduce issues and track changes over time.

Accessing Environment Variables Across Different Test Automation Tools

• Selenium: You can access environment variables using the process.env object in your Selenium tests.

const { Builder, By, Key } = require('selenium-webdriver');
const { expect } = require('chai');

(async function example() {
const driver = await new Builder().forBrowser('chrome').build();

try {
// Access the CI_BUILD_ID environment variable and log it
console.log(`CI Build ID: ${process.env.CI_BUILD_ID}`);

// Navigate to the application's homepage
await driver.get('http://example.com');

// Your test code here
} finally {
await driver.quit();
}
})();

• Cypress: In Cypress, you can access environment variables using the cy.env() command.

describe('My Test', function() {
it('Accesses CI Build ID environment variable', function() {
// Access the CI_BUILD_ID environment variable and log it
console.log(`CI Build ID: ${Cypress.env('CI_BUILD_ID')}`);

// Your test code here
});
});

• Playwright: In Playwright, you can access environment variables using the process.env object as well.

const { chromium, expect } = require('playwright');

(async function example() {
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();

try {
// Access the CI_BUILD_ID environment variable and log it
console.log(`CI Build ID: ${process.env.CI_BUILD_ID}`);

// Navigate to the application's homepage
await page.goto('http://example.com');

// Your test code here
} finally {
await browser.close();
}
})();

Worked Example

Let's walk through a worked example using GitLab CI/CD and Selenium WebDriver:

1. First, define the CI_BUILD_ID variable in your .gitlab-ci.yml file:

variables:
CI_BUILD_ID: $CI_PIPELINE_ID

1. In your test script (e.g., test.js), access the environment variable and log it:

const { Builder, By, Key } = require('selenium-webdriver');
const { expect } = require('chai');

(async function example() {
const driver = await new Builder().forBrowser('chrome').build();

try {
// Navigate to the application's homepage
await driver.get('http://example.com');

// Find an element on the page and send a keystroke to demonstrate accessing the environment variable
const element = await driver.findElement(By.id('some-element'));
await element.sendKeys(`CI Build ID: ${process.env.CI_BUILD_ID}` + Key.RETURN);

// Your test code here
} finally {
await driver.quit();
}
})();

In this example, we've logged the CI_BUILD_ID environment variable to a page element using Selenium WebDriver for demonstration purposes. In your actual tests, you may choose to store the Build ID in a database or log it to a file.

Common Mistakes

• Forgetting to define the environment variable in your CI configuration: Make sure you have defined the CI_BUILD_ID variable correctly within your CI system's settings or configuration files.
• Tip: Double-check that the variable name and value are correct, and that they match the naming conventions used in your test scripts.
• Accessing non-existing environment variables: Ensure that the environment variable you are trying to access is properly set and available in your test script. Check the documentation of your CI platform for information on how to define and access environment variables.
• Tip: If you're unsure whether an environment variable is set, try logging it to verify its existence before using it in your tests.
• Ignoring the importance of version control: Keep your scripts under version control (e.g., Git) so that changes can be tracked, and issues can be easily reproduced. This will help you collaborate effectively with other team members and maintain a history of your test automation efforts.
• Tip: Regularly commit your changes to ensure that your codebase remains up-to-date and easily accessible for collaboration.

Subheadings under Common Mistakes:

• Using incorrect variable names: Ensure that the environment variable name in your test scripts matches the one defined in your CI configuration files.
• Tip: Use a consistent naming convention across your test scripts and CI configuration files to avoid confusion.
• Accessing environment variables outside their scope: Make sure you're accessing environment variables within the correct context (e.g., within a test script or function) and not before they have been set by the CI system.
• Tip: Double-check that your tests are running after the environment variables have been set, usually during the setup phase of your CI pipeline.

Practice Questions

1. How do you define environment variables for a Jenkins project?

• Access the Jenkins web interface, navigate to the "Manage Jenkins" section, and select "Configure System". Scroll down to the "Global Properties" section, where you can add new properties with unique names and values.

1. What is the difference between CI_PIPELINE_ID and CI_BUILD_ID in GitLab CI/CD?

• CI_PIPELINE_ID represents the unique identifier for a pipeline, while CI_BUILD_ID represents the unique identifier for an individual build within that pipeline.

1. How can you use the CI_BUILD_ID variable to store test results in a database?

• You can modify your test script to connect to a database and insert the CI_BUILD_ID along with other relevant data, such as test results or timestamps. This will allow you to track tests across different builds and identify issues more easily.
• Tip: Use an ORM (Object-Relational Mapping) library like Sequelize for Node.js to simplify the process of interacting with databases in your test scripts.

FAQ

Question: What happens if I don't set the CI Build ID environment variable?

• Without setting the CI Build ID, it becomes difficult to trace specific builds and their associated test results, making it harder to reproduce issues and track changes over time.

Question: Can I use different names for the CI Build ID environment variable in my test scripts and CI configuration?

• Yes, you can use different names as long as they are consistent across your test scripts and CI configuration files. However, using a consistent naming convention will make it easier to understand and maintain your test automation codebase.

Question: How do I handle cases where the CI system doesn't provide a unique Build ID for each build?

• In such cases, consider using alternative methods to generate a unique identifier, such as combining timestamps or commit hashes. This will ensure that you have a unique identifier for each build even if the CI system does not provide one directly.
• Tip: You can use libraries like crypto in Node.js to generate random identifiers or hashes of your test data, which can help create unique Build IDs when necessary.