GitLab Project and Package Registry

https://gitlab.com/infometis-public/tdo-data-fetcher-for-cypress

Content

1 GitLab Project and Package Registry
2 Install it
- 2.1 Create a blank cypress project
- 2.2 Install TDO Data Fetcher for Cypress 🥳
3 Some preliminary work
4 Use it
- 4.1 Description of fetchTdoData Function
  - 4.1.1 Purpose
  - 4.1.2 Prerequisites
  - 4.1.3 Function Parameters
  - 4.1.4 Usage Examples
  - 4.1.5 Error Handling
  - 4.1.6 Logging
  - 4.1.7 Output
- 4.2 Example 1 - Define a cypress task an fetch TDO data within specs
  - 4.2.1 Define a cy.task() in cypress.config.js
  - 4.2.2 Create a cypress command
  - 4.2.3 Create the spec
- 4.3 Example 2 - Load TDO Data before run

Install it

Create a blank cypress project

Create a folder

mkdir my-great-cypress-project

Navigate to the folder

cd my-create-cypress-project

Create a Node.js Project

npm init -y

Using npm init -y will skip any questions from npm and create a package.json with defaults based on your current directory name and git configuration (if any). It's particularly useful if you want to start a new project quickly without spending time on initial configuration.

Install Cypress

npm install cypress --save-dev

Open Cypress for initial configuration.

npx cypress open

For this tutorial we have used

E2E testing
Ticked on all configuration files
Chrome browser

Do not chose anything at “Create your first spec” - We’ll create one together.

Close the browser opened by Cypress.

Open your cypress project in your IDE (we are using Visual Studio Code)

You can find more information about installing cypress at:
Install using npm, Yarn, or pnpm | Cypress Documentation | Cypress Documentation

Yay! Your Cypress project is now ready!

Install TDO Data Fetcher for Cypress 🥳

The package is registered on GitLab in the infometis-public namespace (https://gitlab.com/infometis-public/tdo-data-fetcher-for-cypress/-/packages ).

The project name is tdo-data-fetcher-for-cypress.

An easyway to install the package from the registry is directly from the GitLab repository URL

npm install gitlab:infometis-public/tdo-data-fetcher-for-cypress --save-dev

Use --save-dev to install it as a devDependency. devDependencies are not installed in PROD environments.

If you prefer to register GitLab as a registry in your project you can find out more at: https://docs.gitlab.com/ee/user/packages/npm_registry/index.html#authenticate-to-the-package-registry

Check your package.json file to confirm the dependency is listed under devDependencies.

Yeah! You successfully installed TDO’s data fetcher for Cypress!

Some preliminary work

In order to fetch data from your TDO we need to declare two environment (env) variables.

TDO_JIRA_ACCESS_TOKEN
You get your Jira Access Token in Jir. Go to your Jira Profile → Personal Access Tokens, create a new one and add it to the env variable.

TDO_JIRA_API
This is the REST-API URL of TDO for your Jira Instance. You can find more information about the REST-API here: https://infometis.atlassian.net/wiki/x/LAG6Bw
It looks like https://my-example-jira-instance.com/rest/tdo/1.0/.

The easiest way is to create a .env file and add your variables:

Create a .env file
Add your env variables into the file
TDO_JIRA_ACCESS_TOKEN="your-complicated-access-token" TDO_JIRA_API="https://my-example-jira-instance.com/rest/tdo/1.0"
Replace "your-complicated-access-token" with your Jira API token.
Replace "https://my-example-jira-instance.com/rest/tdo/1.0" with your Jira REST API base URL
Test your REST API URL: Append /swagger.json to the URL and confirm it returns a valid JSON response.

Yeah! You are ready to use TDO’s data fetcher for Cypress within your automation work.

Use it

Description of fetchTdoData Function

This utility function fetches Test Data Objects (TDO) from JIRA and prepares them for Cypress testing by converting them into fixtures.

Purpose

The function automates the process of:

Retrieving TDO data from JIRA
Saving the data as JSON files
Creating Cypress fixtures from these JSON files

Prerequisites

Before using this function, ensure you have the following environment variables set:

TDO_JIRA_ACCESS_TOKEN - Your JIRA API authentication token
TDO_JIRA_API - The base URL for the JIRA API

Function Parameters

You can find an explanation of the TDO terms like Type and Environment here:
https://infometis.atlassian.net/wiki/x/k4A-C

Parameter	Required	Default Value	Description

Parameter	Required	Default Value	Description
jiraProjectKey	Yes	--	The JIRA project key (e.g., 'PROJ')
tdoEnv	Yes	--	Target TDO environment ('dev', 'uat', 'prod')
tdoType	Yes	--	Type within environment to fetch
includeLocked	No	false	Whether to include locked TDO items
tdoJsonFolder	No	'tdo-json-files'	Directory for JSON file storage
cypressFixtureFolder	No	'cypress/fixtures'	Directory for Cypress fixtures

Usage Examples

Basic Usage

const { fetchTdoData } = require('tdo-data-fetcher-for-cypress');

await fetchTdoData('PROJ', 'dev', 'userdata');

Including Locked Items

const { fetchTdoData } = require('tdo-data-fetcher-for-cypress');

await fetchTdoData('PROJ', 'uat', 'business_partner', true);

Custom Folder Paths

await fetchTdoData(
  'PROJ',
  'prod',
  'testdata',
  false,
  'custom-json', //tdoJsonFolder
  'tests/fixtures' //cypressFixtureFolder
);

Error Handling

The function will throw an error if:

TDO items cannot be retrieved from JIRA
Required environment variables are missing
File operations fail

Logging

The function includes logging at key points:

Start of TDO data fetch (INFO level)
Successful completion (INFO level)
Failures during execution (ERROR level)

Output

After successful execution, you will find:

JSON files in your specified tdoJsonFolder
Corresponding Cypress fixtures in your cypressFixtureFolder

Example 1 - Define a cypress task an fetch TDO data within specs

In this example, we would like to check the homepage of STORE if it holds several items. This items may change. Our marketing department provides us via TDO with the expected items on the homepage (nice interdisciplinary work ).

Jira Project: TDO
Environment: CypressTest
Type: Products-on-Demoblaze

For our test we need to load the freshest data from tdo and check http://demoblaze.com , if they are visible.

Define a cy.task() in cypress.config.js

cy.task() provides an escape hatch for running arbitrary Node code, so you can take actions necessary for your tests outside of the scope of Cypress. This is great for:
Seeding your test database.
Storing state in Node that you want persisted between spec files.
Performing parallel tasks, like making multiple http requests outside of Cypress.
Running an external process.
task | Cypress Documentation | Cypress Documentation

tdo-data-fetcher-for-cypress needs Node.js filesystem access. This is why a cypress/support .js file won’t work. The support and spec files run in the browser context and tasks in cypress.config.cy run in Node.js context.

// cypress.config.js

const { defineConfig } = require("cypress");
// import function
const { fetchTdoData } = require('@infometis-public/tdo-data-fetcher-for-cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      
      //track if already fetching to prevent duplicate call
      let isFetching = false;

      on('task', {
        // define task to fetch data from tdo
        fetchTdoData: async (tdoConfig) => {
          if (isFetching) {
            console.log('Fetch already in progress, skipping duplicate call');
            return null;
          }
          try {
            isFetching = true;
            console.log('Fetching TDO data with config:', tdoConfig);
            await fetchTdoData(
              tdoConfig.projectKey,
              tdoConfig.environment,
              tdoConfig.type,
              tdoConfig.includeLocked
              // default 'tdo-json-files'
              // default'cypress/fixtures/tdo' 
            );
            return null;
          } catch (error) {
            console.error('Error details:', error);
            throw new Error(`Failed to fetch TDO data: ${error.message}`);
          }
        },
      });
    },
  },
});

Create a cypress command

Custom Commands in Cypress | Cypress Documentation

With a custom command to run the fetchTdoData you can keep your spec file clean because you can handy call the command.

// support/commands.js

// custom command to trigger the cy.task fetchTdoData
Cypress.Commands.add('loadTdoData', (config) => {
    return cy.task('fetchTdoData', config)
      .then(() => {
        // return the generated fixture file
        return cy.fixture(`${config.environment}_${config.type}.json`);
      });
  });

Create the spec

Within our spec in the before-hook we define the required TDO date and use our command to load the data and save them as fixtures before any testcase is running.

Within the testcase we use the created fixture data.

// e2e/powerful-tdo-demo.cy.js

describe('Demoblaze Product Validation', () => {

// Define TDO requirements directly in the spec
// You could also use a seperated config file and import it
    const tdoConfig = {
      projectKey: 'TDO',
      environment: 'CypressTest',
      type: 'Products-on-Demoblaze',
      includeLocked: false,
    };

    let tdoProducts;

    before(function() {
        // use custom command to retrieve tdo items
        return cy.loadTdoData(tdoConfig)
            // receive the generated fixture file and assign it to tdoProducts
            .then((products) => {
                tdoProducts = products;
            });
    });

    beforeEach(() => {
    cy.visit('https://www.demoblaze.com');
    cy.get('.card-block').should('be.visible');
    });
    
    it('should validate all TDO products exist on Demoblaze', () => {
    cy.get('.card-block').then(($products) => {
        tdoProducts.forEach((tdoProduct) => {
        const webProduct = $products.find(`.card-title:contains("${tdoProduct.Name}")`).closest('.card-block');
        expect(webProduct.length, `Product ${tdoProduct.Name} should exist`).to.be.greaterThan(0);
        
        const webPrice = webProduct.find('h5').text();
        const extractedPrice = parseInt(webPrice.replace('$', ''));
        expect(extractedPrice, `Price for ${tdoProduct.Name} should match`)
            .to.equal(parseInt(tdoProduct.Price));
        });
    });
    });
});

Run the testcase with

npx cypress run

tdo-json-files folder with fetched TDO data is created
within the fixtures folder we have the fetched data represented as a cypress fixture json with name tdoEnvironment_tdoType.json
Within the run we can see how and which data are fetched. Helps for debugging.

Example 2 - Load TDO Data before run

In this example, we want to define a script which loads the needed TDO data as fixtures before the cypress tests are running. For instance this could be used within a CI/CD pipeline.

Create a new folder scripts (or name it as you like)

mkdir scripts

Add a new JavaScript file into the folder and name it e.g. fetch-fixture-data-from-tdo.

Import fetchTdoData and create a function where you call fetchTdoData.

// fetch-fixture-data-from-tdo

const { fetchTdoData } = require('@infometis-public/tdo-data-fetcher-for-cypress');

async function run() {
    try {
        await fetchTdoData(
            //define your parameters
            'TDO', //jiraProjectKey
            'CypressTest', //tdoEnv
            'Just-for-Demo', //tdoType
            true //includeLocked
            //'tdo-json-files' -> tdoJsonFolder
            //'cypress/fixtures/tdo' -> cypressFixtureFolder
        );
    } catch (error) {
        console.error('Error fetching TDO data:', error);
        process.exit(1);
    }
}

run();

Execute your script using node <folder>/<file-name>

node scripts/fetch-fixture-data-from-tdo

Another possibility is to create a shorthand command in your package.json

// package.json

{
  "dependencies": {
    (..)
  },
  "devDependencies": {
    (..)
  },
  "scripts": {
    // with that, you can run your script with 'npm run fetch-tdo-standalone'
    "fetch-tdo-standalone": "node scripts/fetch-fixture-data-from-tdo.js"
  }
}

Now you can run the fetch-fixture-data-from-tdo.js script with

npm run fetch-tdo-standalone

The demo project is available at:

https://gitlab.com/infometis-public/demo-my-great-cypress-project