Our Hashnode account will remain live, so you can continue to read the articles we’ve previously published. We’re grateful to everyone who has read, liked and shared our content on Hashnode, and we hope you enjoy visiting our Digital community.

DevOps engineers and developers, discover how you can reduce testing time and improve consistency across your projects

In our OPA policy-based testing of Helm charts blog post, we explored how to enforce standardised rules and best practices in Kubernetes deployments. While a policy-based testing approach significantly enhances security and compliance in Kubernetes environments, this article shifts the spotlight to unit testing for Helm charts.

Unit testing complements policy-based testing by verifying the functional correctness of individual components within Helm charts. Unlike policy testing, which ensures adherence to predefined rules, unit testing validates that each part of a chart behaves as expected under various conditions.

This blog post introduces a solution designed to speed up testing and boost reliability using standardised, customisable blueprint templates that adapt to any chart.

Leveraging the Helm unit test framework

We leveraged the Helm unit test framework as the base of the test templates. This tool allows developers to write unit tests for Helm in YAML, a familiar format within the Kubernetes world. The framework simplifies testing by checking if the rendered YAML output from a chart matches the expected results. For example, a simple test to check if a deployment exists might look like this:

suite: test deployment existence
templates:
  - deployment.yaml
tests:
  - it: should create a deployment
    asserts:
      - hasKind:
          of: Deployment

This example test ensures that the chart generates a Kubernetes deployment resource. Let’s explore a more comprehensive example that showcases various testing techniques.

suite: test comprehensive deployment configuration
templates:
  - deployment.yaml
tests:
  - it: should be of correct kind, apiVersion, and count
    asserts:
      - hasDocuments:
          count: 1
      - isKind:
          of: Deployment
      - isAPIVersion:
          of: apps/v1

    - it: should create a deployment with correct specifications and metadata
      set:
        replicaCount: 3
        image:
          repository: nginx
          tag: 1.19.0
      release:
        name: production
      asserts:
        - equal:
            path: spec.replicas
            value: 3
        - equal:
            path: spec.template.spec.containers[0].image
            value: nginx:1.19.0
        - equal:
            path: metadata.name
            value: production-myapp
        - matchRegex:
            path: metadata.name
            pattern: ^production-.*$
        - isNotEmpty:
            path: spec.template.spec.containers[0].resources
        - contains:
            path: spec.template.spec.containers[0].ports
            content:
              containerPort: 80
        - isNotNullOrEmpty:
            path: metadata.labels
        - equal:
            path: metadata.labels.app
            value: myapp

  - it: should set resource limits
    asserts:
      - equal:
          path: spec.template.spec.containers[0].resources.limits.cpu
          value: 500m
      - equal:
          path: spec.template.spec.containers[0].resources.limits.memory
          value: 512Mi

  - it: should have appropriate security context
    asserts:
      - equal:
          path: spec.template.spec.securityContext.runAsNonRoot
          value: true
      - isNull:
          path: spec.template.spec.containers[0].securityContext.privileged

  - it: should configure liveness probe correctly
    asserts:
      - isNotNull:
          path: spec.template.spec.containers[0].livenessProbe
      - equal:
          path: spec.template.spec.containers[0].livenessProbe.httpGet.path
          value: /healthz

This comprehensive test suite demonstrates a wide range of Helm unit testing capabilities:

Basic structure validation:

• Checks for the correct kind of action (deployment), API version (apps/v1) and document count.

Deployment specifications:

• Uses “set” key to override chart values for testing specific scenarios.

• Verifies replica count, image details and naming conventions.

• Checks for the presence of resource specifications and correct port configuration.

Metadata and labelling:

• Ensures the correct naming convention (combining release name and app name) is used.

• Verifies the presence and content of labels.

Resource management:

• Checks for specific CPU and memory limits, crucial for resource allocation in Kubernetes.

Security configurations:

• Validates security context settings, ensuring the container runs as a non-root user and isn't privileged.

Health checks:

• Verifies the presence and configuration of a liveness probe.

You can find more information on how to define tests here.

While this test suite is suitable for a specific deployment, it is tightly coupled to the “myapp” application and the “production” release. How can we efficiently reuse this test or a set of test suites across various charts without duplicating effort? To make this more versatile, we could introduce placeholders like {{ CHART_NAME }}, {{ RELEASE_NAME }}, {{ CPU_LIMIT }}, {{ HEALTH_CHECK_PATH }}, {{ REPLICA_COUNT }} etc., to make this specific test suite into a reusable blueprint that can be easily adapted to different charts and configurations.

Blueprint unit test templates

A “templated” Helm test suite allows a test to be reused with different charts, aligning with the best practices of modularity and reusability. In other words, we consume blueprint, standardised, pre-written test suites that can be used to suit any project’s needs. For instance, if we have a test that needs to verify the chart name, release name, deployment count and common metadata, the template includes the checks and can be adjusted per project requirements.

suite: test {{ CHART_NAME }} deployment
templates:
  - deployment.yaml
tests:
  - it: should be of correct kind, apiVersion, and count
    asserts:
      - hasDocuments:
          count: {{ DEPLOYMENT_COUNT }}
      - isKind:
          of: Deployment
      - isAPIVersion:
          of: apps/v1
  - it: should have common metadata
    release:
      name: {{ RELEASE_NAME }}
    asserts:
      - equal:
          path: metadata.name
          value: {{ RELEASE_NAME }}-{{ CHART_NAME }}
      - isNotNullOrEmpty:
          path: metadata.labels
  - it: should set resource limits
    asserts:
      - equal:
          path: spec.template.spec.containers[0].resources.limits.cpu
          value: {{ CPU_LIMIT }}
      - equal:
          path: spec.template.spec.containers[0].resources.limits.memory
          value: {{ MEMORY_LIMIT }}

The above test suite can now serve as a versatile blueprint unit test template, which DevOps practitioners can then fine-tune based on their chart’s specific set-up. This approach enables uniform and streamlined testing across diverse Helm charts, guaranteeing that each deployment fulfils the necessary criteria while reducing the labour required to develop and upkeep test suites.

To further streamline this process and fully leverage the benefits of this method, we wrote a custom Python script that converts the blueprints into customised test suites for each unique chart.

Processing the blueprints

To automate the creation of the final unit tests, we use a Python script that processes the blueprint test suites. This script replaces placeholders in the test suites with actual values from a configuration file. This step transforms our generic blueprints into chart-specific test suites. To demonstrate how to use this solution, let’s walk through a practical scenario using the blueprint deployment and ConfigMap test suites. Reference the sample code in the public repository here to follow along.

Preparing the environment

Before we begin, we need to have the following prerequisites installed:

• Helm > v3.x

• Python > 3.10

• Git

• Local Kubernetes cluster: Although not strictly required for testing purposes, setting up a local Kubernetes cluster with tools like minikube is advisable. This enables validation of the Helm charts in a Kubernetes environment.

You can verify installations by running:

helm version
Python --version
git --version

Clone the repository:

git clone https://github.com/nearform/helm-unit-test-templates/
cd helm-unit-test-templates/sample-code

This is the folder structure:

sample-code/
├── README.md
├── mars/
│   ├── Chart.yaml
│   ├── templates/
│   ├── tests/
│   │   ├── deployment_test.yml
│   │   ├── configmap_test.yml
│   │   └── ...
│   └── values.yaml
├── notes_test.yml
├── renderer.py
├── run_tests.sh
└── values.json

Mars is the Helm chart we will use for the demo. The test suite templates are located in the mars/tests/ folder. We’ll focus on deployment_test.yml and configmap_test.yml to illustrate how these test suite templates work. Let’s take a look at the configmap_test.yml file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/helm-unittest/helm-unittest/main/schema/helm-testsuite.json
suite: test {{ CHART_NAME }} configmap
templates:
  - configmap.yaml
tests:
  - it: should be of correct kind, apiVersion, and count
    asserts:
      - hasDocuments:
          count: {{ CONFIGMAP_COUNT | default(1) }}
      - isKind:
          of: ConfigMap
      - isAPIVersion:
          of: v1

  - it: should have common labels
    asserts:
      - isNotNullOrEmpty:
          path: metadata.labels

  - it: should have correct name (standard)
    documentIndex: 0
    release:
      name: {{ RELEASE_NAME }}
    asserts:
      - equal:
          path: metadata.name
          value: {{ RELEASE_NAME }}-{{ CHART_NAME }}

  - it: should not have Helm hook (standard)
    documentIndex: 0
    asserts:
      - notExists:
          path: metadata.annotations

  - it: should contain expected environment variables
    asserts:
      - equal:
          path: data
          value:
            {{ CONFIGMAP_DATA | to_yaml | indent(12) }}

To customise the tests for a specific chart, we’ll need to modify the sample-code/values.json file. This file provides the actual values for the placeholders in the test templates. Let’s update this file with appropriate values for our Helm chart. You’ll notice that placeholders will be replaced when the tests are rendered.

{
    "CHART_NAME": "mars",
    "RELEASE_NAME": "foobar",
    "CONFIGMAP_COUNT": 1,
    "DEPLOYMENT_COUNT": 2,
    "CONFIGMAP_DATA": {
      "TZ": "UTC",
      "JOHN": "DOE"
    }
  }

With the values.json file configured, we’re ready to initiate the testing process. To do this, we’ll invoke the run_tests.sh script, which orchestrates the entire testing workflow as follows:

./run_tests.sh path/to/chart values.json

This command invokes the script with two arguments: the path to the chart we are testing (sample-code/mars) and the values.json file we just modified i.e ./run_tests.sh mars values.json.

Behind the scenes, the script sets in motion a series of operations:

1. It calls renderer.py, a Python script that acts as the engine for our testing framework.

2. The Python script performs several key tasks:

   a. It generates a temporary directory named <chart-name>_rendered, which serves as a “sandbox” for our testing.

   b. The script then duplicates the contents of the original chart into this new directory.

   c. Next, it scans the test folder within mars_rendered for the templated YAML test suites

   d. For each discovered test file, renderer.py it applies the Jinja2 templating engine, substituting the placeholders we discussed earlier with actual values from the values.json file.

   e. The resulting fully formed test files are then saved back into the mars_rendered/tests directory.

3. With the tests now prepared, run-tests.sh invokes the helm unit test command directing it to evaluate the chart in the “sandbox” directory.

4. As the tests execute, you’ll see real-time feedback in the terminal, highlighting any successes or failures.

5. Upon completion of the tests, the script makes a decision:

   a. If all tests pass successfully, it tidies things up by removing the temporary mars_rendered directory.

   b. However, if any tests fail, the script preserves the mars_rendered directory, allowing for inspection of the generated files and diagnosis of any issues.

Fig 1: Test result showing failed and passed tests

The above snapshot shows the results of the tests. Overall, out of 47 total tests across five test suites, 45 passed and two failed, with the entire process being completed in about 146 milliseconds. Scrutinising the test suites in the mars_rendered directory allows you to compare the rendered test expectations against the actual chart output, helping pinpoint the exact source of the discrepancy.

To resolve the ConfigMap test failure, trace the issue by examining the rendered ConfigMap in mars_rendered/templates/configmap.yaml. Compare this with the test expectations in marsrendered/tests/configmaptest.yaml. This investigation will lead you to the env section in the chart's values.yaml file, where you'll need to add the missing JOHN: "DOE" entry under the “plain” subsection to match the test's expectations. This adjustment will ensure the ConfigMap test passes by providing all expected environment variables.

Fig 2: Resolving the ConfigMap data

The deployment test failed — it expected two deployment documents but found only one. This could indicate an issue with the chart's deployment configuration or a mismatch between the expected and actual number of deployments. To address it, we'll modify the values.json file to set DEPLOYMENT_COUNT to 1, aligning with the actual number of deployments in our chart. This change will resolve the deployment test failure.

Fig 3: Resolving the deployment count

After making these changes, we re-run the test script (./run_tests.sh mars values.json) to verify the fixes. By aligning the test expectations with your chart's configuration, both the deployment and ConfigMap tests should pass successfully.

Fig 4: A successful test

Conclusion

DevOps teams can attain substantial efficiency gains and enhanced reliability by embracing these blueprint Helm unit test templates. Complementing policy-based testing, they validate that Helm charts generate Kubernetes resources with expected structures and properties, verifying compliance from a security and organisation perspective. The templates are easy to adapt for specific chart requirements, significantly reduce testing time through reusable templates, ensure consistency with standardised yet customisable structures and improve deployment reliability.

Discover how to lay a foundation that ensures your design system is aligned with an organisation’s short, mid and long-term goals

When considering that two-thirds of companies report using them, it’s clear design systems hold a significant place in tech product ecosystems. They ensure consistency, encourage cohesiveness and help maintain a business’ vision across its products and services.

As with the scope of any project, there will always be variables that require adapting methods. However, crafting a design system for an existing product/organisation can be achieved by focusing collaborative discussions and output around four key pillars:

• Identify, plan and prioritise

• Assess and evaluate

• Communicate, collaborate and build

• Document and plan

Adopting these pillars, fosters clarity, encourages buy-in across teams and enables gradual, thoughtful scaling. Now we’ll explore each of them in detail.

Pillar #1: Identify, plan and prioritise

Work with key stakeholders around the organisation who are involved with the product(s) to identify and clarify problems, pain points and opportunities. Once you’ve done this, decide how to prioritise the work. Some questions that should be asked are:

• What are the common sources of friction? Are there inconsistencies, or technical misinterpretations? Is there an underlying misalignment of values being translated into the product(s)?

• What opportunities present themselves to address the identified problems? Can we fix x by focusing on y?

• How do we ensure we build solid foundations for the design system that allows it to scale and evolve?

• What should we focus on first? What are the basics that can start to deliver real impact quickly and that can start to create ripples of excitement around other parts of the organisation?

Not all of these considerations need to translate into direct actions for early work on a design system, but they can be useful to be aware of as the system grows and evolves in the future.

As part of Nearform’s work with TELUS Digital, the web arm of Canadian telecoms giant TELUS, we facilitated early discovery sessions. These took a deep dive into the root causes and problems that were resulting in fragmented experiences amongst their various products and services.

Through identifying, planning and prioritising, we were able to recommend and build a universal design system, ensuring a seamless experience across all channels. The result was a more robust system that allowed teams around the organisation to design, build and release products — with better UI and UX — much more efficiently than before.

Our partner saw an incredible impact, as Steve Tannock, TELUS Digital’s Director of Platform, Technology & Tools, notes: “Generally the time to market for any new app is about 30-40% less than it was, which is huge!”

Pillar #2: Assess and evaluate

Assess and evaluate the current state of the product(s) and the organisation and how they fit together. Focusing on the following can help to build a holistic view of the current situation:

• Conduct a review of the product(s), examining existing core UI components, accessibility standards and common patterns and behaviours across the product(s).

• Collect the existing styles, components and flows, to assess what needs to go into the core of the design system, and decide how you can then structure the output.

• Optionally, not always required in the first phase, collect other, less tech-focused resources that may complement and inform the product's design. For example, brand guidelines, tone of voice and company values.

You can explore a practical example of the assess and evaluate pillar by reading PUMA’s story of building a global unified design system.

Pillar #3: Communicate, collaborate and build

Regular communication with the business is important, to ensure you’re staying on track to deliver a valuable and scalable system. Here are some ways in which a collaborative approach can help build a better design system:

• UI Components in Figma (or another design tool) should align with existing frontend components. Naming conventions and structures can be aligned to create more cohesive workflows between designers and engineers.

• Validate your work regularly. Staying on track is important. design systems can cover many angles, and it can be easy to veer off course, focusing on output that may not be the immediate priority. Demoing progress and communicating next steps will help to build excitement early, fostering greater advocacy and easier adoption and growth into the future.

Pillar #4: Document and plan

A design system should be usable and understandable by people and teams all around the organisation. Components should be clearly explained, styles should be easily applied and values well communicated.

There are many ways to document a design system — encapsulating everything from simple brand messaging, to code snippets and accessibility guidelines. With documentation, it’s best to start small, and then listen to the consumers (designers, engineers etc) of the design system to see what could add value over time.

Deciding on a documentation platform and structure is a good start. Documentation could initially live within the design tool (Figma, for example). But over time, tools like Storybook, Docusaurus and zeroheight could be considered, as they may provide a better home that is easier to manage and more useful to engineering teams. Building incrementally as the design system grows and matures ensures an even focus is maintained.

In addition to this, to ensure the design system is set up for ongoing success in the future, contribution models and governance planning should be realistically considered to align with team size, capabilities and product roadmaps.

Conclusion: Build a solid foundation then reflect, understand, plan and prioritise future versions

Building a design system for an existing product can deliver real value, bringing greater consistency and awareness within an organisation, whilst setting forth a solid path for new features, capabilities and scaling opportunities.

Although it’s important to understand the goals of each organisation, it’s often best to start small and scale over time depending on needs. However small the first phase of work is, ensuring you work within the four pillars will help to cement a solid base for evolution over time.

Build the first version of the system to solve one or two problems (for example, UI consistency standards for designers), and then look to the future to see how it can be widened out to benefit other areas of the organisation (for example, alignment of brand and guiding principles).

Once you’ve built a solid base, take some time to reflect, understand, plan and prioritise future versions that can elevate the design system from a useful artefact to a comprehensive resource that is a central hub for the whole organisation.

Learn how to enhance test productivity and quality at each stage of the Software Development Life Cycle (SDLC)

There are many blogs and discussions about utilising generative artificial intelligence (GenAI) for quality assurance (QA) activities, which primarily focuses on test cases and automation script generation. In this blog, I explore how we can enhance test productivity and quality at each stage of the Software Development Life Cycle (SDLC) by leveraging GenAI.

By incorporating AI into this process from a QA point of view, I believe the practice of 'Shift Left' (this moves testing activities closer to the beginning of the SDLC) will occur organically. To prove this point, I used ChatGPT and Continue (VSCode extension) to create examples. This article may be useful for anyone involved in software development, but the focus is predominantly on testing activities.

Software Development Life Cycle

There are five main stages in the SDLC:

• Analysis

• Design

• Implementation

• Testing

• Evolution/maintenance

Source: Software Development Life Cycle

I will use the AG Grid’s HR Demo site as a sample application throughout this process. The example task is to add a new functionality to this application as described in the story below:

As a HR system user

I want to add a column for Employee’s nationality next to the Country of Residence

So that I can identify whether employee requires a work permit

Let’s follow each stage of the SDLC using this story to identify how we can enhance QA activities with GenAI.

1. Analysis

In the analysis stage, information is gathered from stakeholders regarding their requirements and expectations of the system.

• User stories are created at this stage.

• A ‘Three Amigos’ session (a Business Analyst, a Developer and a Quality Assurance Tester get together to review requirements) may take place after identifying the requirements.

• Before or during the ‘Three Amigos’ session, we can use ChatGPT to generate test cases for the user stories to explore how much value it adds.

This is what I asked in ChatGPT:

It generated seven test cases. I do not want to bore you with listing all test cases, so I selected a few below that could lead to a discussion to add more details to the requirements for the above story.

So, by generating test cases, we created a checklist of items to verify for the story. If I were to create test cases, I would need focused time to understand the story, followed by at least ten minutes to work on the test cases. In comparison, ChatGPT generated them within five seconds, allowing the 'Three Amigos' participants to start their discussions immediately. By going through this checklist, we can identify additional business and technical requirements, helping to solidify the overall requirements further.

2. Design

After the requirements are approved, they are transformed into blueprints for building the application. This may involve screen designs and prototypes to help visualise the requirements for the overall system and/or individual module designs.

Let’s assume that, after the ‘Three Amigos’ discussions, more details were added to the ‘Nationality’ column as below:

• ‘Nationality’ is selected from the dropdown list.

• Can choose only one nationality.

• This is a mandatory field, a warning message is displayed if nothing is selected.

• An alert pops up for a mismatch between ‘Country’ and ‘Nationality’

• Other logic for the alert (such as ignoring EU nations) is out of scope for this sprint

This UI design was drawn based on the above, improved requirements.

Sample UI design

Let’s generate the test cases by pasting the UI design screenshot into ChatGPT and see if we can identify issues that need to be addressed.

This is what I asked:

It produced seven test cases, which are mostly similar to those for the story. Since this design was created after conducting a requirements analysis based on the earlier test cases, there should be fewer questions raised. I identified one test case that may require further discussion.

The key point here is that since we got well-defined functional requirements during the analysis stage, we can focus on visual and usability requirements during the design review session.

3. Implementation

The actual coding and building of software occurs in this stage. AI can now aid in developing code for both application and unit tests, but as my focus is on QA activities, I will not delve into it. I would like to examine what Test Engineers can do utilising GenAI during this stage.

• Create test tickets: You can ask the GenAI to create a test case against the user story and UI screenshot using the Gherkin language. As it produces test cases for core functionalities, you can spend more time planning and scripting for edge cases. I’m a fan of using Gherkin to create test tickets, as it forces you to break down the code to the smallest testable function.

• Preparing work for automation tests: I used GenAI to create a page object and test files for Playwright using the UI design screenshot.

As I was adding automation test script codes to the repository, I used 'Continue,' a VSCode extension, instead of ChatGPT this time.

I pasted the design screenshot into the prompt section and asked ChatGPT to create a page object and test files.

Since this is a VSCode extension, it has a handy tool for adding generated code to your repository, as shown below:

• Apply to the current file.

• Insert at the cursor.

• Copy and paste the code.

You can see below what it generated.

Page object file

// employeePage.js
const { expect } = require('@playwright/test');

class EmployeePage {
  constructor(page) {
    this.page = page;
    this.employeeRows = page.locator('tr.employee-row');
    this.employeeId = page.locator('td:nth-child(2)');
    this.department = page.locator('td:nth-child(3)');
    this.employeeType = page.locator('td:nth-child(4)');
    this.country = page.locator('td:nth-child(5)');
    this.nationalityDropdown = page.locator('td:nth-child(6) select');
  }

  async getEmployeeCount() {
    return await this.employeeRows.count();
  }

  async getEmployeeId(rowIndex) {
    return await this.employeeRows.nth(rowIndex).locator('td:nth-child(2)').textContent();
  }

  async getDepartment(rowIndex) {
    return await this.employeeRows.nth(rowIndex).locator('td:nth-child(3)').textContent();
  }

  async getEmployeeType(rowIndex) {
    return await this.employeeRows.nth(rowIndex).locator('td:nth-child(4)').textContent();
  }

  async getCountry(rowIndex) {
    return await this.employeeRows.nth(rowIndex).locator('td:nth-child(5)').textContent();
  }

  async selectNationality(rowIndex, nationality) {
    await this.employeeRows.nth(rowIndex).locator('td:nth-child(6) select').selectOption(nationality);
  }

  async assertEmployeeDetails(rowIndex, expectedId, expectedDepartment, expectedEmployeeType, expectedCountry) {
    const employeeId = await this.getEmployeeId(rowIndex);
    const department = await this.getDepartment(rowIndex);
    const employeeType = await this.getEmployeeType(rowIndex);
    const country = await this.getCountry(rowIndex);

    expect(employeeId).toBe(expectedId);
    expect(department).toBe(expectedDepartment);
    expect(employeeType).toBe(expectedEmployeeType);
    expect(country).toBe(expectedCountry);
  }
}

module.exports = { EmployeePage };

Test file

// employeeTest.spec.js
const { test, expect } = require('@playwright/test');
const { EmployeePage } = require('./employeePage');

test.describe('Employee Table Tests', () => {
  let employeePage;

  test.beforeEach(async ({ page }) => {
    employeePage = new EmployeePage(page);
    await page.goto('https://your-application.com/employee-table');
  });

  test('should display employee table', async () => {
    const employeeCount = await employeePage.getEmployeeCount();
    expect(employeeCount).toBeGreaterThan(0);
  });

  test('should display correct employee details', async () => {
    await employeePage.assertEmployeeDetails(0, '0001', 'HR', 'Permanent', 'USA');
    await employeePage.assertEmployeeDetails(1, '0002', 'IT', 'Contract', 'Canada');
  });

  test('should select nationality from dropdown', async () => {
    await employeePage.selectNationality(1, 'American');
    // Add assertions to verify the selected nationality
  });
});

It’s usable, but definitely needs some time to review it. However, I found this saves quite a bit of time compared to manually creating these files — it’s a good base to work from. This also reminds me to inform developers to add test IDs and roles for accessibility (a11y) to each element!

4. Testing

Different types of tests are executed to ensure that the intended functionalities are implemented. Unintended behaviours are reported during this stage.

All QA preparation work has been aided and enhanced by GenAI at every stage up until this point. It's now time for QA Engineers to use some elbow grease and let their experience and skills shine!

• Execute functional testing: Add results and evidence to test tickets. Raise bugs if necessary.

• Exploratory testing: As Test Engineers may free up time by utilising GenAI, they can perform experience-based exploratory testing. This may help catch issues that scripted test cases cannot.

• Complete automation test script: Identify what test to automate then update and add codes to the base files which were created by GenAI.

• Create a test report: This is something GenAI can do. I created a sample bug report asking ChatGPT as below.

This command generated decent reports, including 'Description' and 'Steps to Reproduce.' Though I misspelt "width", it correctly assumed and generated the report. A few tweaks were needed, but, again, it saves time, allowing Test Engineers to focus on what truly matters at this stage — performing various types of tests and applying their experience to ensure the quality of newly implemented functionalities.

5. Maintenance

The maintenance stage occurs after the deployment of production. It involves improving, adapting and evolving the software. New requirements may arise from real user feedback. If production bugs are identified, they will be fixed, tested and released. Whether it involves fixing production bugs or implementing new requirements, the steps of SDLC stages 1-4 should be followed.

During the maintenance stage, automated tests need to be updated and maintained. Since the application is now in production, you can provide the URL to the GenAI to generate additional Playwright tests. This allows the AI to capture real locators.

For instance, let’s say a new business requirement states that 'Check' is no longer an available option for the payment method. In this case, additional tests need to be created. I used ‘Continue’ as shown below:

And it generated the below test.

// paymentMethodColumnTest.spec.js

const { test, expect } = require('@playwright/test');

test.describe('Payment Method Column Test', () => {
  let page;

  test.beforeAll(async ({ browser }) => {
    page = await browser.newPage();
    await page.goto('https://www.ag-grid.com/example-hr/');
  });

  test.afterAll(async () => {
    await page.close();
  });

  test('should not contain "Check" in Payment Method column', async () => {
    // Get all the cells in the Payment Method column
    const paymentMethodCells = await page.$$eval('div[col-id="paymentMethod"] div.ag-cell-value', (cells) =>
      cells.map((cell) => cell.textContent.trim())
    );

    // Check if none of the cells contain the value "Check"
    expect(paymentMethodCells).not.toContain('Check');
  });
});

It looks OK but, unfortunately, this did not correctly verify the column. Again, you can use it as a base and update it.

Conclusion

You may already be practising 'Shift Left', but, as demonstrated above, this approach can be further accelerated with GenAI. By scrutinising requirements and designs more thoroughly in the early stages of the SDLC, more time is freed up for Test Engineers to focus on higher-value tasks like experience-based exploratory testing and scripting efficient automated tests.

While GenAI offers significant support, Test Engineers must still fully understand and be capable of manually performing all QA activities. Exercising good judgment is crucial in deciding which tasks can be delegated to AI and which require personal attention.

GenAI can serve as governance throughout each stage of the SDLC, ensuring that processes are followed. By generating test cases, GenAI provides a checklist that acts as a safeguard before progressing to the next stage. A good checklist is one of the simplest yet most effective tools for maintaining quality — not only in software but in nearly any field. I recall reading an article about how the use of a surgical checklist cut infection and death rates by half (ref: National Library of Medicine).

Could a similar approach reduce production bugs by half if we implement test cases at every stage of the SDLC? While it's hard to quantify, I believe that whether they are UI/UX, requirements, or functional bugs, this approach will undoubtedly reduce the number of issues that slip through to production.

We spare you the pain of assessing these two automation tools by looking at how they compare to each other

I have worked with various automation tools throughout my career — starting with QuickTest Professional (QTP), now called Unified Functional Testing (UFT), and, most recently, Playwright. One of my least favourite tools in the past was Nightwatch. However, it seems that Nightwatch has improved significantly, so I thought I'd give it another look and see how it stands up to Playwright today!

This article is for Software Test Engineers. I hope I can spare you some pain in comparing tools and maybe even share some practical knowledge about these modern testing frameworks. Empowered with that knowledge, we can all make informed decisions when choosing a testing framework.

Built-in functionalities

When I first used Nightwatch back in 2016/2017, I don’t recall any of the below functionalities being built-in. Instead, we had to code them explicitly. Fast forward to 2024, and these built-in features are now available in both Nightwatch and Playwright.

1. Auto wait and auto retries

Both Nightwatch and Playwright automatically wait for elements to appear before attempting to interact with them. For example, if your test requires you to enter a username into an input box but the screen takes time to load, both tools will keep checking for the input box to be available until they time out. As a result, you can remove the 'wait until' code for potentially slow-loading pages, making the tests clearer and easier to read. The default timeout setting is five seconds for Nightwatch and 30 seconds for Playwright, but this can be reconfigured in the configuration file.

The automatic retry feature also simplifies the test script. When an assertion fails, it automatically re-asserts the failed line a specified number of times, which can be configured in the configuration file.

2. Handling of pop-up messages

Both Nightwatch and Playwright can handle pop-up messages by explicitly waiting for them. However, Playwright takes it a step further by making it easier to handle pesky, unpredictable pop-ups that appear at different times using page.addLocateHandler(). When an overlay is detected at any point during the test, Playwright first calls the handler, and then proceeds with the specified action to remove the overlay. This feature is unique to Playwright.

test('pop-up test', async({page}) => {
    await page.goto('https://www.techlistic.com/p/selenium-practice-form.html');
    await page.addLocatorHandler(
      page.getByRole('heading', { name: 'Privacy & Transparency' }),
      async () => {
          // This line is executed whenever overlay is detected.
        await page.click('#ez-accept-necessary');  
      });

      await expect(page.getByRole('heading', { name: 'Demo Automation Practice Form' })).toBeVisible();
      await page.locator('input[name="firstname"]').fill('test-firstname');
  })

Playwright addLocateHander() example

3. Reporting tool

Both of these automation tools come with stylish HTML reports and the frameworks add screenshots when a test fails. However, I found Nightwatch's report easier to navigate, as everything can be viewed on one screen. With Playwright, you have to navigate back and forth to check individual test results.

Nightwatch HTML report

Playwright HTML report

You have to open the individual test to see the details

4. Screenshots

Both Nightwatch and Playwright can take screenshots explicitly in code. Also, via a config file, you can enable automatic screenshots for failing tests.

Nightwatch

Test file

browser.saveScreenshot('./screenshots/screenshot.png')

nightwatch.conf.js

test_settings: {
    default: {
      screenshots: {
        enabled: true,
        path: 'screens',
        on_failure: true
      },

Playwright

Test file

await page.screenshot({ path: 'screenshot.png' });

playwright.config.js

use: {
    screenshot: 'only-on-failure',
  },

5. Test recorder/code generator

Nightwatch uses a Chrome extension that can automatically generate tests by recording user actions. From the DevTools, you can record multiple tests and export them to Nightwatch. While it can be a bit clunky to use, it allows you to record actions and add assertions. However, as seen in the exported script, the locators it captures are not very optimised (we should always choose ‘asserting by role’ over ‘selector’ to test accessibility).

Chrome recording

Exported script

describe("nightwatch", function () {
it("tests nightwatch", function (browser) {
  browser.windowRect({width: 1705, height: 693})
  .navigateTo("https://www.nearform.com/")
  .click("ul.nav_right > li:nth-of-type(2) > a")
  .click("#firstname-13c6a12c-2dbc-4455-a6cc-694b8bf39cb8")
  .setValue("#firstname-13c6a12c-2dbc-4455-a6cc-694b8bf39cb8", "test")
  .click("div.hs_submit input")

        .waitForElementVisible("text/Please complete all", function(result) {
          if (result.value) {
            undefined
          }
        })

  .end();
  });
});

In comparison, Playwright has its own test recorder called codegen, which can be launched by running the below code:

npx playwright codegen

Test code is generated in real-time as you navigate through the page. It is intuitive and quite user-friendly. You can record actions, capture page locators, and add assertions. Additionally, it supports device emulation and allows you to specify geolocation, language, and time zone. The power of this feature is hard to describe. Check out all of the features here.

VSCode extension

Running and scripting tests gets a whole lot easier with a VSCode extension. Both Nightwatch and Playwright have extensions, but they have slightly different functionalities. Let’s compare them.

Nightwatch extension

Test Explorer

• Nightwatch tests integrate directly into VSCode's built-in 'Test Explorer' into a dedicated section. You can execute tests from this section or directly from a test file.

Browsers

• Choose ‘Browser’ from the ‘Nightwatch Environment’ section.

• You can only select one browser at a time from this section.

Settings

• Select ‘Headless’ or ‘Headed’ mode.

• Open report automatically after tests have run.

• Set the number of parallels.

Playwright extension

Test Explorer

• All executable Playwright tests appear in this section.

Browsers

• You can select multiple browsers.

Settings

• Select ‘Headless’ or ‘Headed’ mode.

• Launch ‘Trace Viewer’, which enables you to follow tests step by step along with screenshots and information you can get from a browser dev tool, such as network trace. This makes debugging easier.

Tools

• One feature that sets Playwright apart from Nightwatch is its tool for selecting locators. I found the 'Pick Locator' feature to be very handy. You can point to the element you need, and the page locator is captured into VSCode. By pressing the Enter key on the captured locator, it is copied and is then ready to be pasted into your code.

• The ‘Record New’ functionality is almost exactly the same as codegen. The only difference is that it creates a new test file, then the test code is generated there as you navigate through the screen.

I rarely use codegen because I can do most jobs from the VSCode extension tools. If you haven’t used them before, I highly recommend giving them a try.

Language support, syntax comparison and debugging

Below, we look at language support, syntax and debugging for Nightwatch and Playwright.

1. Language support

Nightwatch supports JavaScript and TypeScript, making it ideal for teams working within a JavaScript ecosystem. Playwright, however, offers broader language support, including Java, Python, and .NET, in addition to JavaScript and TypeScript.

2. Syntax comparison

Up until v2, Nightwatch uses a traditional callback or promise style. Each command, like .findByRole or .url, relies on a callback function that contains assertions or further actions. WebDriver is used to execute tests.

*However, v3 (July 2023) introduced synchronous syntax.

Nightwatch test — up to v2

module.exports = {
    'nightwatch - assert filter and title': function(browser){
        browser.url(browser.launch_url);
        browser
            .element.findByRole('button', {name: 'Reject All'}).click();
        browser
            .assert.visible('input[placeholder="Filter any column..."]')
            .assert.titleEquals('Demo - Performance Grid');
    }
}

Nightwatch using async/await (from v3)

module.exports = {
    'nightwatch - assert filter and title': async function(browser) {
    await browser.url(browser.launch_url);
    await browser.element.findByRole('button', { name: 'Reject All' }).click();
    await browser.assert.visible('input[placeholder="Filter any column..."]');
    await browser.assert.titleEquals('Demo - Performance Grid');
    }
};

Playwright uses async/await syntax and tests are executed directly in the browser.

test('playwright - assert filter and title', async ({ page }) => {
    await page.goto('/example');
    await page.getByRole('button', { name: 'Reject All' }).click();
    // break for debug here
    await expect(page.getByPlaceholder('Filter any column...')).toBeVisible();
    await expect(page).toHaveTitle('Demo - Performance Grid')
  });

3. Debugging

Previously, Nightwatch only supported callback-based syntax, which made debugging more challenging. However, this was addressed in mid-2023, making debugging simpler and allowing for a more meaningful comparison between Nightwatch and Playwright. Let’s compare what happens when you try to debug the above sample code.

1. Put in a break line, then click the ‘Reject All’ button.

2. Execute tests in debug mode.

3. The test reaches the break line.

Conclusion

Nightwatch has significantly improved over the years, and I am impressed by how user-friendly it has become. However, I still prefer Playwright over Nightwatch due to some limitations that are difficult to overcome. For instance, Nightwatch requires the setup and maintenance of WebDriver. Up until mid-2023, Nightwatch only supported callback-based syntax, which made debugging more challenging. Ease of debugging is crucial when determining the cause of a test failure, as you need to quickly ascertain whether it is a valid failure or an error in the test script. While Nightwatch now supports async/await syntax, it came a bit too late, as Playwright has been using this feature since 2020.

Playwright also supports more languages, making it adaptable to a wider range of development stacks. The framework is easier to maintain since there is no need for a separate WebDriver, and tests are executed directly in the web browser. Its code is simpler to script and read, which makes the test development process more efficient. Thus, I’ll be sticking with Playwright until another new tool emerges for evaluation.

We share essential steps every developer should follow to ensure their website performs at its best, with specific insights for Next.js

In today's fast-paced digital landscape, the need for top speed and performance for your website has never been more critical. Whether it's to capture user attention, improve search engine optimisation (SEO) or simply provide a seamless browsing experience, performance optimisation is a priority for website developers across all stacks.

At Nearform we've had the privilege of working on a variety of projects, ranging from building apps from the ground up to critical interventions in ongoing developments. This extensive experience has given us deep insights into performance optimisation. We frequently collaborate with clients who demand exceptional scalability and performance, and our proven strategies have consistently delivered outstanding results.

Website performance is a fundamental aspect of user satisfaction and engagement

Lately, many developers have made Next.js their web development framework of choice. This is due to its ability to enhance SEO and improve search engine rankings, driving more traffic and engagement to their website.

The rise in popularity of Next.js can be attributed in part to its robust performance capabilities. With built-in server-side rendering (SSR) and static site generation (SSG), Next.js empowers developers to create blazing-fast web applications without compromising on functionality or user experience.

However, even the most powerful tools require fine-tuning to unleash their full potential. This guide will cover general optimisation techniques, with a specific focus on Next.js, to help you achieve superior performance and better rankings.

As we dive into the details of optimising Next.js website performance, it's essential to recognise that speed is not just a technical concern — it's a fundamental aspect of user satisfaction and engagement. Users expect websites to load quickly and seamlessly, regardless of the underlying technology stack, these are some of the things to be aware of:

• 47% of users expect a page to load in under 2 seconds

• 100ms in latency costs 1% in sales

• Load times over 1s for a mobile site increase visitor bounce rate by 90%

While our focus is on Next.js, it's worth noting that many of the performance optimisation techniques we'll discuss can be applied across various technology stacks —- irrespective of the framework, the principles of performance optimisation remain largely consistent.

Quick tips from Nearform’s website optimisation checklist

Drawing from our past experiences, we've developed a checklist that can serve as a go-to guide for website optimisation. This checklist encapsulates some of the essential steps every developer should follow to ensure their website performs at its best. While we include general optimisation techniques, we also provide specific insights for Next.js.

Here are some quick tips from our checklist to get you started, and remember, our team at Nearform is always ready to provide expert guidance tailored to your specific needs.

Must-do: Set up effective monitoring

Before delving into the intricacies of performance optimisation, it's essential to establish a robust monitoring system tailored to your application. Effective monitoring not only allows you to track the impact of optimisations over time but also facilitates the identification of potential bottlenecks, empowering you to make informed decisions for further performance enhancements.

For real-time monitoring and visualisation, leveraging tools like Prometheus and Grafana is paramount. Prometheus excels in collecting metrics from both your application and infrastructure, while Grafana offers comprehensive visualisation and analysis capabilities. Together, they enable you to scrutinise crucial performance indicators and help with identifying performance bottlenecks and resource constraints, paving the way for targeted optimisations.

In addition to real-time monitoring, investing in performance monitoring tools like NewRelic or Datadog provides invaluable insights into your application's performance at a deeper level. By analysing this data, you can fine-tune your application's performance, ensuring seamless user experiences across various scenarios.

Vital check: Perfect your caching setup

Caching is one of the most effective ways to improve the performance of your web application. When implementing caching, it's essential to identify what resources and data should be cached, how long should those be cached for and when the cache should be refreshed.

When dealing with large volumes of data, slow performance can be a common issue. Even fetching cached data can unexpectedly take a significant amount of time. Our experience reveals the efficacy of compressing data (utilising formats like gzip or brotli) before caching, as it can notably enhance load times. It's worth noting that certain caching solutions offer this compression option, presenting a potential game-changer. Keeping a vigilant eye on such features could yield significant performance improvements.

Necessary validation: Confirm connection reuse

Connection reuse is a crucial strategy for optimising the performance of web applications. By reusing existing connections, instead of establishing new ones for each request, you can reduce latency, and improve throughput and the overall speed of your application. This is particularly important for applications that make numerous HTTP requests or database queries.

Reusing connections eliminates the need for repeated TCP handshakes, reducing the time it takes to establish a connection and start data transfer while also reducing the computational and memory overhead associated with establishing and tearing down connections, leading to more efficient resource utilisation.

Ensure that your web server is configured to support Keep-Alive connections. If your application makes frequent database queries, consider using connection pooling to reuse database connections. When making HTTP requests from your Next.js application, opt for HTTP clients that support Keep-Alive. For instance, Node.js's HTTP and HTTPS modules inherently support Keep-Alive, while some third-party libraries, such as axios, may require explicit configuration for this feature. Set an appropriate timeout value to strike a balance between reusing connections efficiently and avoiding the risks of keeping idle connections open for too long.

Optimise your CDN strategy

Content Delivery Networks (CDNs) play a vital role in improving the performance and reliability of web applications by distributing content closer to users.

Select a CDN provider that suits your needs. Popular options include Cloudflare, AWS CloudFront, Akamai and Fastly. Each provider offers different features and pricing models, so choose one that aligns with your performance and budget requirements. Enable compression on your CDN to further reduce the size of transmitted data. Most CDNs support Gzip and Brotli compression. Use HTTP headers to control how and when your assets are cached.

Data efficiency: Optimise __NEXT_DATA__

The __NEXT_DATA__ object is a global variable injected by Next.js into every page on the client side to help with faster rendering and it can grow in size extremely fast (read more).

Often times in cases when Next.js apps have performance issues, __NEXT_DATA__ is a good place to focus for performance improvements. While the __NEXT_DATA__ object in Next.js is a powerful tool, misusing its capabilities can lead to serious performance penalties. The key thing here is to only keep crucial and essential data about the page in this object.

Try to review the data and remove any piece of data that is not needed for the initial rendering. We’ve seen huge improvements just by double-checking for duplicate data or removing certain properties that weren’t needed initially (and you definitely have some of those).

Picture perfect: Ensuring ongoing image optimisation

Lighthouse, is an open-source automated tool for measuring website performance and quality. It often flags images as significant performance issues, especially on mobile. Common problems include improperly sized and unoptimised images. To address these issues, the Next.js next/image component is highly effective:

• Automatic optimisation: Images are optimised based on device characteristics, reducing bandwidth and improving CLS metrics.

• Lazy loading: Images load as they enter the viewport, enhancing initial page load times.

• Modern formats: Supports WebP and AVIF formats, which offer better compression and quality.

• Responsive images: Automatically selects appropriate sizes for various screen sizes.

• Placeholders: Provides visual feedback during loading, improving perceived performance.

Future-proof: Maintaining the latest in Next.js

Maintaining an up-to-date Next.js application is crucial for ensuring optimal performance. Regular updates bring numerous benefits, including performance enhancements, security patches, and new features.

Each Next.js release often includes optimisations that enhance performance. These updates can reduce build times, improve server-side rendering speed, and enhance client-side performance.

Cut the clutter: Removing unused JS/CSS

Eliminating unused JavaScript and CSS is a key strategy for optimising the performance of your Next.js application. Removing unused code reduces the overall size of your application, leading to quicker load times and a more responsive user experience.

Metrics such as First Contentful Paint (FCP), Time to Interactive (TTI), and Largest Contentful Paint (LCP) improve when there is less code to parse, compile, and execute. Smaller files are more efficient to cache, making repeated visits faster and reducing server load.

What can you do? Analyse your bundle and get rid of unnecessary code; make sure the project is set up to use tree shaking, dynamic imports can help in certain situations.

Building performance: piece by piece

Every project is unique and fine-tuning an application’s performance will be unique to that application. The above list serves as a guide to follow to shave off some big wins when it comes to performance tuning. The most important thing is to have a strategy and improve the performance piece by piece.

Our example sets an AI agent the aim of retrieving, calculating and plotting financial data

In this article, we explore what Microsoft's SemanticKernel is, what the advantages of using it are, and provide a simple example of how to use Semantic Kernel to create an AI agent to accomplish the task of displaying different value graphs for a stock in a specific time period.

This provides a reasonably complex example that uses external data sources and custom data formatting.

What is Semantic Kernel?

Microsoft’s Semantic Kernel is a software development kit (SDK) that integrates Large Language Models (LLMs) with programming languages like C#, Python, and Java. The SDK does this by allowing us to define programming functions as plugins that can be easily chained together in a few lines of code.

Another major feature of Semantic Kernel is its ability to automatically orchestrate (or coordinate) plugins using AI. Simply provide the Semantic Kernel with an LLM and the plugins you need, then create a planner. When you ask the planner to achieve a specific goal, the Semantic Kernel will execute the plan for you.

What is an AI agent?

An AI agent is a software program designed to perform tasks autonomously to achieve predetermined goals. It interacts with its environment (such as code functions, APIs, and data sources) and independently determines the best tools and actions to use for each task. AI agents can adapt to changes in their environment, learn from experiences, and improve their performance over time.

In summary, the user provides the goal which the AI should achieve and the AI will determine and execute the best approach to achieving that result.

AI agent: Financial stock plotter

We utilised Semantic Kernel to create an AI agent. The aim of the agent is to retrieve financial data, calculate the drawdown of the data, and finally plot both the data and the drawdown.

The above diagram shows how the agent communicates with the required APIs and functions to perform the desired tasks. A step-by-step explanation is available below:

1. The user asks a question via the terminal: User: give me details on Apple over the last 6 months

2. The agent will process the query to retrieve the required fields from the user’s query:

a. ticker_name: AAPL

b. period: 6mo

3. The agent will call a function to retrieve the historical data from the Yahoo finance API. This data includes a variety of information on the stock over the period provided. The values we are interested in are: dateand close

a. date: the day the stock values were at the level indicated

b. close: the value of the stock at the time of closing of the financial markets on that day

4. The agent will call a function to calculate the drawdown

a. The drawdown is a financial measure that looks at the price of a stock at a certain point in time, gets the previous max value the stock held, and subtracts the max from the current value. The drawdown is a negative score as the current value is never greater than the cumulative max value up to the date we are looking at. The closer the drawdown is to zero, the closer the stock is to its maximum value.

5. The agent will then generate dynamic Python code to plot the data in a valid format using pandas and matplotlib.

6. Finally, the agent will refactor the code to attach the data calculated earlier on to the code just generated, then execute it

The plotted equity data (closing value) and drawdown data

Creating an agent

At the time of writing, Semantic Kernel allows four types of agents, called planners.

Sequential planner

Sequential planner takes a goal (prompt) and runs through the plugins provided to the agent at creation time, in the order requested by the goal. The loop will continue until the goal is complete. This is the agent we used to accomplish our goal.

The process our planner follows is shown below:

Stepwise planner

An agent that will run through the user request and process it step by step. It differs from the sequential planner by only running a specific agent against a part of the query. This allows the agent to break down the query into individual parts and run those against the plugin.

An example is if we asked “What would be the temperature in New York if we added 10 degrees to the current temperature?” the stepwise planner will be able to split the weather API call and the math problem from the query and run them separately, giving answers based on them.

Handlebar planner

The main advantage of the handlebar planner over the stepwise planner is the usage of the handlebar templating language to generate the plan. This is due to the majority of LLMs already supporting the handlebar interface when dealing with prompts, which helps provide improve the accuracy of the response (in this case the agent plan). In opposition to the stepwise planner that uses XML when generating the plan. Using this language we can also provide loops and conditions that otherwise would only be available in coding languages.

Another advantage of this planner is the fact that the return value of the serialised function planner.getPlan is a readable text file that can be stored and reloaded at a later date. However, this planner is not available in the Python version of the kernel, as of the time of writing.

Custom planner

Semantic Kernel offers us the ability to create our agent with custom rules. This involves more complexity but also gives more freedom to the developer to create the agent in the way they intend. It is particularly useful when you want human intervention during the agent planning stages, for example, to provide new variables or access custom data sources.

At the time of writing, the team behind Semantic Kernel intends to deprecate the Handlebar and Stepwise planners, in favour of this approach.

Our agent

The below code demonstrates how we created our agent using the Sequential planner:

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.functions import KernelArguments
from semantic_kernel.connectors.ai.function_call_behavior import FunctionCallBehavior
from plugins import CodeRefactor, FinancePlugi
from semantic_kernel.planners import SequentialPlanner

# Create the Kernel Instance
kernel = Kernel()

execution_settings = OpenAIChatPromptExecutionSettings(
    service_id="chat"
)

# Configure AI service used by the kernel
kernel.add_service(
    OpenAIChatCompletion(service_id=service_id,
    api_key=open_ai_key,
    ai_model_id=ai_model_id),
)

# Adding our custom plugins to the kernel
kernel.add_plugin(parent_directory="./plugins", plugin_name="ChatPlugin")
kernel.add_plugin(plugin=FinancePlugin(), plugin_name="FinancePlugin")
kernel.add_plugin(parent_directory="./plugins", plugin_name="ChartPlugin")
kernel.add_plugin(plugin=CodeRefactor(), plugin_name="CodePlugin")

# Define the details to be passed to the planner
arguments = KernelArguments(settings=execution_settings)
arguments["user_input"]= "Show me the drawdown for Apple stock"

goal = '''Based on the user_input argument,chat with the AI to get
                    the ticker_name and period if available,
           extract the data for a ticker over time,
           create a drawdown, plot the chart, 
           refactor the code to include the drawdown data.
       '''

# Create the plan
plan = await planner.create_plan(goal = goal)

# Execute the plan
result = await plan.invoke(kernel=kernel, arguments=arguments)

Steps to create an AI agent

1. Create the kernel Instance: This is the starting point to map our planner to the plugins and LLM. We can generate more than one planner with the same kernel, allowing for parallel agents if needed.

2. Configure AI service used by the kernel: This allows the tool to interpret user input into the right parameters and ensure the right tool is called at the right time to accomplish the goal.

3. Adding our custom plugins to the kernel: This enables non-standard LLM calls to be usable by our agent

4. Define the details to be passed to the planner: These include standard LLM settings (temperature, token limit, …) and function handling instructions.

5. Create the Plan: Define the “System Message” for the planner as the goal. This instructs the LLM about the behaviour we expect our agent to have. The goal should be straightforward and use similar terminology available in the tools' descriptions.

6. Execute the plan: Connects the details defined in step 4 to the plan and triggers the invocation step for the plan to start.

Plugins

A Semantic Kernel plugin is a software component designed to extend the LLM's functionality by either granting the LLM capabilities that it did not previously have (code plugins) or defining the purpose of the LLM invocation to a specific topic (prompt plugins).

In contrast to tools supported natively by the LLM (such as function invocation), a plugin is not attached directly to the model but is placed within the planner. The planner will then generate a step-by-step approach and see if any of the steps of the goal are associated with the plugin and will call the function in question.

The main drawback of plugins is the requirement for a string response from the functions, as structured data is easier to manipulate in code and we don’t have to use resources ‘stringifying’ and parsing all our content. This is due to Semantic Kernel not being aware of the planner's plan before it is in action, making it so that all responses need to be compatible with an LLM call, which defaults to text.

Code plugins

Code plugins expand functionality by granting the LLM new “skills” it did not have access to prior.

The function is a standard Python function. To transform this to a code input we added the function decorator called kernel_function. This decorator expects 2 arguments:

• name, which is the name of the function to be referenced when attaching the plugin.

• description, which is a string value that indicates what the intention of the function is. This helps the planner identify when it needs to call this function and when it should avoid it.

The two main use cases for code plugins are the data based on the developer’s intention, or accessing external APIs. We demonstrate both abilities below:

Accessing an external API

import yfinance as yf
import pandas as pd
from semantic_kernel.functions.kernel_function_decorator import kernel_function

# defines this function as a plugin function
@kernel_function(
  name="financial_info",
  description="gets the historic details for a stock")
def financial_info(
  self,
  TICKER_AND_PERIOD):

  if not TICKER_AND_PERIOD:
     raise Exception("No ticker value provided")

  args = json.loads(TICKER_AND_PERIOD)
  ticker_name =  args["ticker_name"]
  period =  args["period"]

  if ticker_name is not None:    
     ticker = yf.Ticker(ticker_name)
     time = period if period is not None else '1y'
     data = ticker.history(period = time)
     data.index = data.index.strftime('%Y-%m-%d')
     data["Close"] = data["Close"].round(4)

     print('data retrieval complete')

     return data.to_json()

As shown in the code snippet above, we want to retrieve the historical data for a specific ticker using the Yahoo Finance API.

We created the base function for it when we instantiate a Ticker based on the input. Notice that the model is able to convert the string input to the required variables, before calling the plugins.

Then, we use the historical data to get the closing prices for the period specified. Finally, we manipulate the pandas DataFrame to format the style of the columns Close and the date index as these will be used in future steps of the process.

Processing data

import yfinance as yf
import pandas as pd
from semantic_kernel.functions.kernel_function_decorator import kernel_function

@kernel_function(name="drawdown", description="Calculate the drawdown values for the stock")
def drawdown(self, data_json: Annotated[str, "the data from the stock"]):
   data =  pd.read_json(StringIO(data_json))

   data['Peak'] = data['Close'].cummax()
   data['Drawdown'] = data['Close'] - data['Peak']
   data = data.drop(columns=["Peak"])

   print('drawdown calculated')

   return str(data.to_json(orient='split'))

We want to calculate the drawdown for the data based on the formula: drawdown = current - cummax. Pandas provides us with the functionality required to perform this calculation.

Our original data looked like this:

After the function run our data looks like this:

Now that we have our data available, we will be moving to a prompt plugin to generate dynamic code.

Prompt plugins

Prompt plugins are used to alter the original intention of the LLM being invoked by providing it with new instructions. The plugin files are a prompt file and a JSON file. The prompt is the instructions that the LLM must abide by. The JSON file contains the LLM values to take into account.

The content of these files looks like this:

You are a chatbox that will retrieve the ticker_name and the period
(if provided) for the company in input in a json format

Example:
    query: Give me details on Apple over the last year
    result: ticker_name = NVDA, period= 1y

    query: Give me details on Nvidia
    result: ticker_name = NVDA, period= null

    query: What colour is the sky
    result: No ticker available

input={{$user_input}}

{
  "schema": 1,
  "description": "From the data generate code that will map the data over a time period",
  "execution_settings": {
    "default": {
      "max_tokens":4096,
      "temperature": 0.1,
      "stop_sequences": [
        "[Done]"
      ]
    }
  }
}

The keyword filenames skprompt and config will let the planner know that these are prompt plugins. The prompt file will contain a straight prompt instruction similar to an LLM Model system message, which provides instructions to the model.

The config file will determine the kwargs information for the prompt. This is the equivalent of writing the below code but with the correct mappings, and the input required based on the part of the goal this step is aiming to achieve:

f = open('skprompt.txt', 'r')
response = client.chat.completions.create(
  model=current_model,
  messages=[
     {"role": "system", "content": f.read()},
     {"role": "user", "content": "user_input": user_input}
  ],
  temperature=0.1,
  max_tokens=4096,
  stop=stop_sequence,
)

The plugins are then attached to the kernel instance before we instantiate the planner. Hence, any planners we may have will benefit from the plugins provided.

Conclusion

Various tools are available to create GenAI agents for specific tasks, each with its strengths and weaknesses. Semantic Kernel is an interesting tool for creating straightforward agents that perform relatively well for simple tasks.

As illustrated above, we can use Semantic Kernel to quickly create AI agents that can retrieve and modify data as well as perform LLM requests to accomplish a predetermined goal. Semantic Kernel is capable of utilising the LLM to create the best approach to a task and which plugins to consume to ensure the task is completed.

The two main advantages explored in this article are Plugins and Planners. Plugins are versatile and powerful and require minimal alteration to functions for code plugins, and standard text values for prompt plugins. The variety of the planners and the ease of creation makes them very reliable for different types of agents.

Comparing Maestro with other popular tools for mobile UI automation

In the ever-evolving landscape of mobile app development, efficient and effective testing is crucial. Mobile testing ensures that applications work seamlessly across different devices and platforms. By choosing the right tools, teams can significantly enhance their productivity and the quality of their applications.

This article explores the features of Maestro, a promising tool for mobile UI automation, and compares it with other popular tools such as Robot Framework Appium Library and WebdriverIO.

Real-world application of Maestro

A common challenge in mobile UI testing is managing the complexity of test setups and ensuring consistent results across different environments. Maestro offers a solution by enabling users to perform tests using a simple YAML syntax, which can be easily understood and written by anyone in the organisation. This flexibility allows teams to quickly adapt to changes and make reliable decisions promptly.

A simple Maestro test case

Here is an example of how a Maestro test case is structured using YAML:

appId: org.wikipedia
---
- tapOn: "ADD OR EDIT.*"
- tapOn: "ADD LANGUAGE"
- tapOn:
    id: ".*menu_search_language"
- inputText: "French"
- assertVisible: "Français"
- tapOn: "Français"
- tapOn: "Back"

This example demonstrates a simple yet comprehensive test case for a hypothetical Wikipedia application:

1. appId: Specifies the ID of the application to be tested.

2. tapOn: "ADD OR EDIT.*": Simulates a tap on any element whose text matches the pattern "ADD OR EDIT".

3. tapOn: "ADD LANGUAGE": Simulates a tap on the "ADD LANGUAGE" button.

4. tapOn (with id): Simulates a tap on an element whose ID matches the pattern "menu_search_language".

5. inputText: "French": Inputs the text "French" into the input field.

6. assertVisible: "Français": Verifies that the text "Français" is visible on the screen.

7. tapOn: "Français": Simulates a tap on the "Français" option.

8. tapOn: "Back": Simulates a tap on the "Back" button to return to the previous screen.

Localised testing challenges

Running tests in different languages can introduce complications, and this is true for any testing approach. With Maestro, this issue arises when the simulator's language settings do not match the language expected by the test scripts. For instance, if your simulator is set to Italian and your tests are designed for an English interface, the tests will fail because the locators (which depend on text strings) will not match.

A running test with Maestro

To address this, Maestro provides the ability to set up and configure simulators for different locales. Here are some solutions:

• Locale configuration: Ensure that the simulator's locale matches the language of your test scripts. You can configure the locale using Maestro's command-line options:

maestro start-device --platform ios --device-locale en_US --os-version=15

• Use of IDs and universal locators: Instead of relying solely on text strings, use element IDs and universal locators that remain consistent across different languages.

• Parameterised tests: Create parameterised test scripts that can adapt to different locales by using variables for text strings, making it easier to run the same tests in multiple languages.

By implementing these strategies, you can minimise discrepancies and ensure more reliable test results across various language settings with Maestro.

Emulator setup

Setting up emulators for different locales and operating system versions can be a challenge with Maestro. For instance, initiating a test run on an iOS simulator in British English requires specific commands and configurations:

maestro start-device --platform ios --device-locale en_GB --os-version=17

It’s important to note that Maestro supports specific OS versions, such as iOS 15, 16, and 17, at the time of writing. For the most current list of supported versions, refer to the Maestro documentation. Setting up the appropriate emulator can be tricky, especially for those not familiar with mobile testing environments.

Flaky tests and element inspection

A critical aspect of mobile testing is the accurate inspection of elements within the application. Maestro Studio is a tool within Maestro that helps testers design and execute tests through a visual interface. However, relying solely on Maestro Studio may not always allow for precise element inspection, leading to flaky tests if elements are not correctly identified.

Element IDs are unique identifiers for UI elements within an app, similar to how IDs are used in web applications. These IDs are crucial for ensuring tests interact with the correct elements. Without access to the app’s codebase, it can be challenging to inspect and identify these elements accurately.

To address this, tools like Appium Inspector can be used alongside Maestro. Appium Inspector provides a comprehensive solution for inspecting app elements, allowing testers to accurately identify and interact with elements even without direct access to the codebase. A common practice is to use such inspectors to identify elements and reference the app’s codebase when possible to retrieve IDs.

By combining these tools, testers can ensure more reliable and accurate test results, reducing the likelihood of flaky tests.

Maestro Studio Locators Inspector

AI integration in Maestro

One of Maestro’s main features is its integration of artificial intelligence (AI), which assists users in various ways:

• Automated element identification: The AI helps automatically identify UI elements, reducing the time needed to write test cases.

• Intelligent test recommendations: Based on the application’s structure and previous test cases, Maestro's AI can suggest test steps and improvements, ensuring more comprehensive test coverage.

Thanks to these AI capabilities, Maestro not only reduces setup time but also enhances the reliability of tests. Teams can then focus more on the core functionalities of their applications, ensuring higher quality and a faster time-to-market. This integration of AI into the testing process is relatively new, making Maestro an innovative tool in the mobile testing landscape.

Maestro Studio AI Feature

Parallel test execution

While Maestro simplifies many aspects of mobile testing, it does not support running tests in parallel across different simulators directly. Even with two simulators and two terminals open, parallel execution is not possible. There is, however, the option to run tests in the cloud within a mobile development environment, although this incurs additional costs.

Comparing mobile testing tools

Choosing the right tool for mobile test automation can significantly impact efficiency, accessibility, and test maintenance. Here, we compare three main tools: Maestro, Robot Framework Appium Library, and WebdriverIO.

Maestro

Maestro is designed for simplicity and ease of use, making it ideal for teams with limited coding experience. Its YAML-based syntax allows for quick test creation and execution, which is particularly useful for small projects or teams new to automation. The integration of AI in Maestro Studio provides intelligent test recommendations and automated element identification, enhancing productivity and test reliability.

Robot Framework Appium Library

Robot Framework Appium Library leverages the power of Python and the flexibility of Robot Framework. It is suited for teams with a solid coding background who need a robust and versatile testing solution. This tool offers comprehensive support for various mobile testing scenarios but requires more setup and a steeper learning curve compared to Maestro.

WebdriverIO

WebdriverIO is a JavaScript-based framework that supports both web and mobile testing. It is highly extensible and integrates well with various CI/CD pipelines, making it suitable for teams already familiar with JavaScript. WebdriverIO strikes a balance between usability and flexibility, offering powerful features for both beginner and advanced testers.

Feature comparison table

When to use each tool

• Maestro: Recommended for teams seeking quick setup and ease of use, especially when team members have limited coding knowledge. Ideal for small to medium projects where speed and simplicity are crucial.

• Robot Framework Appium Library: Best for teams with strong coding skills who require a highly versatile and robust testing solution. Suitable for complex projects that demand extensive customisation.

• WebdriverIO: Great for teams with JavaScript expertise looking for a flexible tool that can handle both web and mobile testing. Perfect for projects that benefit from extensive integrations and a balance of ease of use and power.

By understanding the strengths and appropriate use cases for each tool, teams can make informed decisions to enhance their mobile testing strategy.

Final considerations

Based on our experience, we consider Maestro an exceptionally valuable tool for those new to mobile UI automation. Its simplicity in setup and use makes it particularly suitable for both small projects and those looking to gain a basic understanding of UI automation without facing a steep learning curve. However, for more complex projects, it might be necessary to opt for a more powerful and versatile tool.

Maestro serves as a precious resource for organisations aiming to improve the quality of their mobile applications through efficient and manageable testing processes. By reducing the complexity and time required to configure and execute tests, Maestro enables teams to focus more on innovation, reducing time to market and enhancing the quality of the final products.

The insights we gained from implementing cross-cloud access

In the ever-evolving landscape of cloud computing, it's increasingly common to face scenarios that necessitate cross-cloud access. Whether it’s accessing AWS services from an Azure Kubernetes Service (AKS) cluster or leveraging Azure resources from an AWS Elastic Kubernetes Service (EKS) cluster, these scenarios present unique challenges that demand innovative solutions.

A project where we migrated to AKS: Background and challenges

In one of my recent projects, we encountered the need to migrate an application from a self-managed Kubernetes cluster hosted on AWS to Azure Kubernetes Services. This transition was not just a simple lift-and-shift, as it also involved enabling secure access to cloud resources across different cloud providers.

Official documentation often falls short in covering these complex scenarios comprehensively, leading to potential gaps in implementation. Through this blog post, I aim to share insights gained from implementing cross-cloud access, focusing on the integration between Azure and AWS. This discussion will cover two key scenarios:

1. Enabling access to AWS services from an Azure AKS cluster.

2. Facilitating access to Azure services from an AWS EKS cluster.

Our goal is to foster a harmonious interaction between these two cloud giants, overcoming the common obstacles encountered in such integrations and securely granting access without the need for sharing credentials.

Proposed solution: AWS IAM Role for Service Account (IRSA) and Azure workload identity federation

Each cloud provider offers a bespoke solution to ensure secure access within their managed Kubernetes clusters. AWS employs the IRSA, allowing workloads to safely assume roles that provide necessary permissions to access cloud resources. Concurrently, Azure has rolled out Azure Workload Identity to streamline identity and access management. Both platforms require a specific add-on to inject tokens correlated with the service account.

Central to these mechanisms is OpenID Connect (OIDC), a robust and time-tested protocol foundational to identity verification across disparate platforms. OIDC is pivotal for securely interconnecting Azure and AWS services, offering a secure, scalable, and adaptable authentication framework that is crucial to our approach, guaranteeing smooth and dependable identity management across cloud environments.

OpenID Connect primer

OpenID Connect (OIDC) is a crucial protocol for verifying identities across various cloud platforms, enhancing the OAuth 2.0 framework by securely verifying a user's identity through an authorisation server and enabling access to resource servers. Although frequently used, the complexities of OAuth 2.0 and OIDC can initially be overwhelming, prompting a deeper exploration to understand how these protocols facilitate secure cross-cloud access.

Understanding OAuth 2.0 and OIDC

In essence, accessing specific data or services requires authorisation to ensure the request is permitted and identity verification to confirm that the requestor is indeed who they claim to be. While OAuth 2.0 handles authorisation, it does not inherently confirm the requester's identity. OIDC addresses this gap by adding a layer of identity verification atop OAuth 2.0.

Core components involved:

• User Data: The data or services needed, managed by a resource server.

• Resource Owner: The owner of the data or service.

• Authorisation Server: Authorises access requests.

• Relying Party/Client Application: Initiates access requests. Upon approval from the Resource Owner, the Authorisation Server issues an "Access Token."

This framework ensures that data access is both authenticated and authorised.

OAuth 2.0 Flows

The OAuth 2.0 protocol includes various flows to accommodate different scenarios:

1. Authorisation code flow: Used in systems like "Sign in with Google," where a user logs in to share specific data, receiving an access token in exchange for an authorisation code.

2. Implicit flow: Previously popular in applications that couldn't securely store secrets, such as single-page applications. Now, due to security concerns, more secure methods like the Authorisation Code Flow with PKCE are recommended.

3. Password credential flow: Employed when there is a strong trust relationship between the resource owner and the client, such as personal mobile apps.

4. Client credential flow: Ideal for server-to-server interactions, where a client application uses its credentials to obtain an access token directly, granting access to the resource server.

In all these flows, OIDC enhances the process by adding an "ID Token" to verify the user's identity, providing a robust identity layer over the existing OAuth 2.0 authorisation structure. For further details, you can refer to the official OpenID Connect documentation.

OIDC in cloud Kubernetes environments

In this section, I share detailed authentication steps for AWS IRSA with Amazon EKS and Azure Workload Identity in AKS.

AWS IRSA with Amazon EKS

In AWS IRSA (IAM Roles for Service Accounts) within Amazon EKS, the OAuth flow used is akin to the Client Credentials Grant. This design is specifically tailored for machine-to-machine communication where an application acts on its own behalf rather than acting for a user. AWS IAM plays a critical role here, validating service account tokens issued by EKS and providing scoped AWS credentials for accessing AWS resources.

Detailed authentication steps in AWS IRSA using an OIDC provider:

1. OIDC provider configuration:

• Within AWS EKS, an OIDC provider is configured to connect the Kubernetes cluster's identity system with AWS IAM. This OIDC provider is not a separate service but a configuration within AWS IAM that trusts the Kubernetes cluster's service account tokens.

• The OIDC provider in AWS is set up to trust tokens issued by the Kubernetes cluster, meaning it recognises these tokens as authentic credentials.

2. Service account token:

• Each Kubernetes pod can be assigned a specific service account. This account has a JWT (JSON Web Token) associated with it, which is automatically managed and rotated by EKS.

• This JWT includes claims that identify the particular service account and permissions.

3. Authentication process:

• When a pod in EKS needs to access AWS resources, it retrieves its JWT from the file system (mounted by EKS into the pod).

• The pod or the application inside it then presents this JWT in a request to AWS IAM as part of the API call to assume the linked IAM role.

4. Token validation:

• AWS IAM, acting as the OIDC provider, validates the JWT against the issuer URL, the audience (aud), and other claims included in the JWT. These validations ensure that the token is indeed issued by the trusted EKS cluster and that it is intended for the specific IAM role it is requesting.

• This validation process is crucial as it confirms the authenticity and appropriateness of the request, effectively authenticating the service account's identity based on the OIDC standards.

5. Credential issuance:

• Upon successful validation, AWS IAM issues AWS credentials (access key, secret key, and session token) to the pod. These credentials are temporary and scoped to the permissions defined in the IAM role associated with the service account.

6. Using AWS resources:

• With these credentials, the pod can make authenticated and authorised API calls to AWS services, operating within the permissions boundaries set by the IAM role.

For more information, refer to the official documentation.

Azure Workload Identity in AKS

Similarly, in Azure Kubernetes Service (AKS), the Azure Workload Identity utilises a flow comparable to the OAuth 2.0 Client Credentials Grant. This setup allows Kubernetes pods to securely access Azure resources by leveraging Azure Active Directory (AAD) identities. The AKS manages the association between Kubernetes service accounts and AAD identities, facilitating a secure and scalable authentication method without user interaction.

Detailed authentication steps in Azure AD Workload Identity for Kubernetes:

1. OIDC provider configuration:

Azure AD (Active Directory) Workload Identity uses Azure Active Directory (AAD) as the OIDC provider. This configuration involves setting up Kubernetes to issue tokens that Azure AD can trust. The integration between Kubernetes and Azure AD allows Kubernetes service accounts to use these tokens to authenticate against Azure resources securely.

2. Service account token:

In Azure Kubernetes Service (AKS), each pod can use a Kubernetes service account that is automatically integrated with Azure AD using the Azure Workload Identity setup. The tokens issued to these service accounts are projected into the pod's file system and are used for authentication with Azure AD.

3. Authentication process:

• A pod needing to access Azure resources will use the token provided to its Kubernetes service account.

• This token is presented to Azure AD as part of the request to access Azure resources.

4. Token validation:

• Azure AD validates the Kubernetes service account token using established trust configurations. It checks the issuer, the audience, and other claims in the token to ensure it is valid and issued by a trusted Kubernetes cluster.

• This validation is crucial as it ensures the token's authenticity and appropriateness for the requested Azure resource access.

5. Credential issuance:

• Once the token is validated, Azure AD issues an Azure access token to the pod.

• This token is specifically scoped to the permissions that are assigned to the Azure AD identity linked with the Kubernetes service account.

6. Using Azure resources:

• The pod uses the Azure access token to make authenticated and authorised API calls to Azure services.

• These services validate the Azure access token and provide access based on the permissions configured for the Azure AD identity.

For more information, refer to the official documentation.

Running IRSA in AKS

Following in the footsteps of IRSA in EKS, we simply need to substitute the EKS cluster with the AKS cluster. AKS hosts a public endpoint to expose the OpenID Configuration via the OIDC Issuer URL. Next, we need to create an IAM Identity Provider (IDP) that points to the AKS OIDC Issuer URL. This IDP is then associated with an IAM Role as a trust policy, along with a policy that grants the required permissions needed to access AWS services. Finally, we annotate the service account in the AKS cluster with the IAM Role ARN (Amazon Resource Name) that we created earlier.

In detail, we need to follow the below steps:

1. In Azure: Create a resource group that hosts the AKS cluster.

2. In Azure: Create an AKS cluster and enable the OIDC Issuer.

3. In Azure: Create a service account (SA)

4. In Azure: Get the OIDC Issuer URL.

5. In AWS: Create a resource (an S3 bucket) to check the access.

6. In AWS: Create a role providing access to the S3 bucket created above.

7. In AWS: Create an identity provider that points to the AKS OIDC Issuer URL.

8. In Azure: Annotate the SA in AKS with the IAM Role ARN that we created above.

9. In Azure: Install the amazon-eks-pod-identity helm chart.

10. In Azure: Create a workload that uses the SA and try accessing the AWS Service in this case S3 bucket.

In the next section, we’ll now get our hands dirty. I have used azure cli in the various steps you’re about to read — make sure that you have authenticated to Azure using your credentials.

At the end of the next section, our solution will look like this

Create an AKS cluster

Run the below commands and note that we set some env variables which will build up over time and will be used later down the line.

# Set required environment variables.
export LOCATION="eastus"
export RESOURCE_GROUP_NAME="rg-aks-az-identity"
export CLUSTER_NAME="aks-az-identity"
export SERVICE_ACCOUNT_NAMESPACE="default"
export SERVICE_ACCOUNT_NAME="workload-identity-sa"
export SUBSCRIPTIONID=$(az account show --query id -o tsv)
export AZURE_TENANT_ID=$(az account show -s ${SUBSCRIPTIONID} --query tenantId -otsv)

# Create resource group.
echo "Creating a resource group: ${RESOURCE_GROUP_NAME}"
az group create --name ${RESOURCE_GROUP_NAME} --location ${LOCATION}

# Create AKS cluster.
az aks create \
    --resource-group ${RESOURCE_GROUP_NAME}  \
    --name ${CLUSTER_NAME} \
    --network-plugin azure \
    --enable-managed-identity \
    --generate-ssh-keys \
    --node-count 1 \
    --enable-oidc-issuer \
    --outbound-type  loadBalancer 

# Output the OIDC issuer URL.
export SERVICE_ACCOUNT_ISSUER=$(az aks show --resource-group ${RESOURCE_GROUP_NAME} --name ${CLUSTER_NAME} --query "oidcIssuerProfile.issuerUrl" -otsv)

# Get the kubeconfig for the Kubernetes clusters.
az aks get-credentials --name ${CLUSTER_NAME} --resource-group ${RESOURCE_GROUP_NAME}

# Create a new Service account.
kubectl create sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE}

Create an AWS resource for testing the access from AKS

First, you need to create an Amazon S3 bucket. Replace your bucket name with your desired bucket name and your region with the AWS region you want to use. Copy a file into the S3 bucket for testing later. Note that we created a dummy text file named test-file.txt for testing the access.

export BUCKET_NAME=irsaaccess
export REGION=us-east-1
aws s3api create-bucket --bucket ${BUCKET_NAME} --region ${REGION}

aws s3 cp test-file.txt s3://${BUCKET_NAME}/test-file.txt

Create an AWS IAM Identity provider

Create an Identity provider from the AWS console with the Azure OIDC Issuer URL from the above SERVICEACCOUNTISSUER and audience as sts.amazonaws.com

You need three pieces of information:

1. OIDC Issuer Url from AKS.

2. Audience which is sts.amazonaws.com.

3. CA Root cert thumbprint.

The first two pieces of info exist already, so now we need to get the CA Root Cert thumbprint.

# Extract the OIDC host from the issuer URL
export OIDC_ISSUER=$(echo $SERVICE_ACCOUNT_ISSUER | sed 's|https://||')
export OIDC_HOST=$(echo $SERVICE_ACCOUNT_ISSUER | sed 's|https://||' | cut -d'/' -f1)

# Fetch the certificate chain from the OIDC host
echo | openssl s_client -connect $OIDC_HOST:443 -servername $OIDC_HOST -showcerts 2>/dev/null | awk '/-----BEGIN CERTIFICATE-----/{cert=$0 "\n"; next} /-----END CERTIFICATE-----/{cert=cert $0 "\n"; last_cert=cert; next} {cert=cert $0 "\n"} END{print last_cert > "last_cert.pem"}' 

# Calculate the SHA-1 fingerprint of the root CA certificate and format it how AWS Expects it.
CERT_THUMBPRINT=$(openssl x509 -in last_cert.pem -fingerprint -noout -sha1 | sed 's/sha1 Fingerprint=//' | tr -d ':')

rm last_cert.pem

export IAM_IDP_ARN=$(aws iam create-open-id-connect-provider --url $SERVICE_ACCOUNT_ISSUER --client-id-list "sts.amazonaws.com" --thumbprint-list $CERT_THUMBPRINT | jq -r '.OpenIDConnectProviderArn')

Create an IAM Policy to grant access to the S3 bucket

Use the below policy JSON and save it to a file locally as s3-policy.json to consume later. Note the bucket name matches the name of the S3 bucket we created earlier.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::irsaaccess",
                "arn:aws:s3:::irsaaccess/*"
            ]
        }
    ]
}

Run the below command to create the custom policy. Please make sure that you configure aws cli.

export POLICY_ARN=$(aws iam create-policy --policy-name S3ListReadPolicy --policy-document file://s3-policy.json | jq -r '.Policy.Arn')

Create a trust relationship policy document

Use the templated JSON below to create a trust policy document and save it as trust-policy-template.json.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "$IAM_IDP_ARN"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "$OIDC_ISSUER:sub": "sts.amazonaws.com"
                },
                "ForAnyValue:StringEquals": {
                    "$OIDC_ISSUER:sub": [
                        "system:serviceaccount:$SERVICE_ACCOUNT_NAMESPACE:$SERVICE_ACCOUNT_NAME"
                    ]
                }
            }
        }
    ]
}

We have a templated trust policy file named trust-policy-template.json and using the envsubst CLI replace the the template values from env variables which is ready for us to consume.

envsubst < trust-policy-template.json > trust-policy.json

Now this has generated a new file trust-policy.json with the required configuration.

Create an IAM Role by attaching a trust policy

You create the role using the AWS CLI by specifying the role name and the trust relationship policy document. Save your trust policy JSON to a file, for instance, trust-policy.json, and then run the below AWS CLI command

export WEB_IDENTITY_ROLE=$(aws iam create-role --role-name MyWebIdentityRole --assume-role-policy-document file://trust-policy.json | jq -r '.Role.Arn')

Once the role is created, you can attach permission policies to define what resources and actions the role can access. If you already have a policy ARN to attach, you can use:

aws iam attach-role-policy --role-name MyWebIdentityRole --policy-arn $POLICY_ARN

Annotate the Service account for IRSA

kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} eks.amazonaws.com/role-arn="${WEB_IDENTITY_ROLE}" --overwrite
kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} eks.amazonaws.com/audience="sts.amazonaws.com" --overwrite
kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} eks.amazonaws.com/sts-regional-endpoints="true" --overwrite
kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} eks.amazonaws.com/token-expiration="86400" --overwrite

Deploy the pod identity webhook

This webhook is for mutating pods that will require AWS IAM access and it can be installed using the helm chart below:

https://artifacthub.io/packages/helm/jkroepke/amazon-eks-pod-identity-webhook

Note that cert-manager is a pre-requisite for this add-on and you can install this from the official documentation https://cert-manager.io/docs/installation/.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml

helm repo add jkroepke https://jkroepke.github.io/helm-charts/
helm install amazon-eks-pod-identity-webhook jkroepke/amazon-eks-pod-identity-webhook

Run a workload in the AKS that needs S3 bucket access

Note that we are deploying a pod using the service account created earlier in this setup. This pod utilises the Amazon aws-cli image to execute some CLI commands and test the access.

cat <<EOF | kubectl apply -f - 
apiVersion: v1
kind: Pod
metadata:
  name: awscli
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
  labels:
    app: awscli
spec:
  serviceAccountName: ${SERVICE_ACCOUNT_NAME}
  containers:
  - image: amazon/aws-cli
    command:
      - "sleep"
      - "604800"
    imagePullPolicy: IfNotPresent
    name: awscli
  restartPolicy: Always
EOF

After deployment, proceed to test the access with the following commands:

kubectl exec -it awscli -n ${SERVICE_ACCOUNT_NAMESPACE} -- aws sts get-caller-identity

kubectl exec -it awscli -n ${SERVICE_ACCOUNT_NAMESPACE} -- aws s3 ls s3://irsaaccess

Running the Azure Workload Identity in an AWS EKS cluster

The following sections cover the steps required for you to run the Azure Workload Identity in an AWS EKS cluster, from creating the AWS EKS cluster to validating access.

Create the AWS EKS cluster

I am using eksctl CLI for provisioning the cluster and please setup your aws cli with the required credentials. In my case, I am loading a default profile on my machine.

export AWS_DEFAULT_PROFILE=default

# Define variables
export CLUSTER_NAME="my-eks-cluster"
export REGION="us-west-2"
export NODE_TYPE="t3.medium"
export NODE_COUNT=1
export KUBERNETES_VERSION="1.28"

# Create the EKS cluster with OIDC identity provider
echo "Step 1: Creating EKS Cluster: $CLUSTER_NAME with OIDC identity provider"
eksctl create cluster \
  --name $CLUSTER_NAME \
  --version $KUBERNETES_VERSION \
  --region $REGION \
  --nodegroup-name "standard-workers" \
  --node-type $NODE_TYPE \
  --nodes $NODE_COUNT \
  --nodes-min $NODE_COUNT \
  --nodes-max $NODE_COUNT \
  --managed \
  --with-oidc

# Check if the cluster was created successfully
if [ $? -eq 0 ]; then
    echo "EKS Cluster $CLUSTER_NAME created successfully."
else
    echo "Failed to create EKS Cluster $CLUSTER_NAME."
fi
export OIDC_URL=$(aws eks describe-cluster --name $CLUSTER_NAME --query "cluster.identity.oidc.issuer" --output text)

export AZURE_SUBSCRIPTION_ID=$(az account show --query id -o tsv)

export AZURE_TENANT_ID=$(az account show -s ${AZURE_SUBSCRIPTION_ID} --query tenantId -otsv)

Install Azure Workload Identity

helm repo add azure-workload-identity https://azure.github.io/azure-workload-identity/charts
helm repo update
helm install workload-identity-webhook azure-workload-identity/workload-identity-webhook \
   --namespace azure-workload-identity-system \
   --create-namespace \
   --set azureTenantID="${AZURE_TENANT_ID}"

Create an Azure KeyVault for testing

export RESOURCE_GROUP_NAME="rg-aws-access-az"
export LOCATION="eastus"
export KEYVAULT_NAME="kv-identity-azwi1"
export KEYVAULT_SECRET_NAME="secret"

# Create keyvault and secret
az keyvault create --resource-group ${RESOURCE_GROUP_NAME} \
   --location ${LOCATION} \
   --name ${KEYVAULT_NAME}

az keyvault wait --name ${KEYVAULT_NAME} --created

az keyvault secret set --vault-name ${KEYVAULT_NAME} \
   --name ${KEYVAULT_SECRET_NAME} \
   --value "Test"

export KEYVAULT_URL=$(az keyvault show -g "rg-aks-az-identity" -n ${KEYVAULT_NAME} --query properties.vaultUri -o tsv)

Create a Managed Identity to federate access to a KeyVault

export IDENTITY_NAME="aws-access-az"

az group create --name ${RESOURCE_GROUP_NAME} --location ${LOCATION}

az identity create --name ${IDENTITY_NAME} --resource-group ${RESOURCE_GROUP_NAME} --query principalId -o tsv

export USER_ASSIGNED_IDENTITY_CLIENT_ID="$(az identity show --name "${IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP_NAME}" --query 'clientId' -otsv)"
export USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show --name "${IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP_NAME}" --query 'principalId' -otsv)"


az keyvault set-policy --name ${KEYVAULT_NAME} \
  --secret-permissions get \
  --object-id ${USER_ASSIGNED_IDENTITY_OBJECT_ID} \
  --resource-group ${RESOURCE_GROUP_NAME}  \
  --subscription ${AZURE_SUBSCRIPTION_ID}

az identity federated-credential create \
    --name "kubernetes-federated-credential" \
    --identity-name ${IDENTITY_NAME} \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --issuer ${OIDC_URL} \
    --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"

Create a service account in EKS and annotate

export SERVICE_ACCOUNT_NAMESPACE="azworkload"
export SERVICE_ACCOUNT_NAME="azworkload"
kubectl create ns ${SERVICE_ACCOUNT_NAMESPACE}
kubectl create sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE}

kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} azure.workload.identity/tenant-id="${AZURE_TENANT_ID}" --overwrite
kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} azure.workload.identity/client-id="${USER_ASSIGNED_IDENTITY_CLIENT_ID}" --overwrite

Deploy the workload in EKS

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: kv-read
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: ${SERVICE_ACCOUNT_NAME}
  containers:
    - image: ghcr.io/azure/azure-workload-identity/msal-go
      name: oidc
      env:
      - name: KEYVAULT_URL
        value: ${KEYVAULT_URL}
      - name: SECRET_NAME
        value: ${KEYVAULT_SECRET_NAME}
  nodeSelector:
    kubernetes.io/os: linux
EOF

Validate access

To check that we are able to access the secret from the KeyVault, check the logs of the pod kv-read from above which would display the secret value. Note that the image used here uses the Microsoft Authentication Library (MSAL) go library to make use of the Workload Identity to access the KeyVault.

Conclusion

OIDC plays a crucial role in verifying identities across various cloud platforms, simplifying the complex process of integrating identity verification into OAuth 2.0. It allows for seamless, secure communication between cloud providers by ensuring that identities are authenticated properly before granting access to resources. This is particularly beneficial in scenarios where services from multiple cloud providers, like AWS and Azure, need to interoperate securely without sharing credentials directly.

Azure has abstracted much of the complexity involved in setting up the OIDC provider, offering a more user-friendly experience compared to AWS. Azure's Workload Identity integration with Azure Active Directory (AAD) provides a streamlined process where the identity management is tightly coupled with the Azure ecosystem, reducing manual configurations and potential errors.

AWS, while more complex in its setup, offers robust and flexible configurations through its IAM Roles for Service Accounts (IRSA) mechanism. This approach, although requiring a deeper understanding and more detailed configuration, allows for finely-tuned access control and extensive customization options, catering to advanced use cases and specific security requirements.

References

• Obtain the thumbprint for an OpenID Connect identity provider

• Create an OpenID Connect provider on Azure Kubernetes Service (AKS)

• Server Certificate

• Diving into IAM Roles for Service Accounts

We assess if Bruno is able to do everything Postman does

This blog post is aimed at individuals who use Postman or any other API development or testing tools in their projects. Throughout this post, we will explore the key features of Bruno, an alternative tool to Postman, and highlight the significant benefits it brought to our projects.

Postman, a reliable tool for API testing

When it comes to API testing, Postman has been the tool of choice for countless organisations. Utilised for its easy-to-use interface, Postman simplifies the API testing process and allows you to incorporate response validation tests using JavaScript, enabling users to ensure the accuracy and reliability of API responses.

Another big advantage of Postman is its flexibility when using different environments. Whether you’re testing locally, on staging servers, or in production environments, Postman provides a streamlined user experience, allowing users to adapt their testing strategies with ease.

Why look for an alternative to Postman?

In one of our projects we used GraphQL queries tailored to each environment, and we needed to ensure thorough testing across different setups. We implemented an HTML report feature, offering a visually engaging summary of our findings.

This report not only facilitated clear communication of our test results to our stakeholders, but also aided in identifying any discrepancies or areas for improvement. We were also able to streamline our testing process by integrating our collection into the CI/CD pipeline using Newman. This integration allowed for nightly executions of the collection without encountering any operational issues, enabling continuous monitoring of the services' performance and stability.

In late 2023, Postman announced it was making some significant modifications to its pricing and functionality structure. We were using the free desktop version, now known as the lightweight API, which became impractical for our needs.

While the prospect of upgrading to the enterprise version to access the necessary functionalities seemed plausible, it unveiled a dealbreaker for our client: data security.

Transitioning to the enterprise version mandated data synchronisation with the cloud, a feature that clashed with our client's security protocols. Further compounding this challenge was the absence of an offline version in Postman's offerings, except for the lightweight API. Consequently, we had to identify a suitable alternative tool that could accommodate our testing needs while adhering to our client's security standards.

Introducing Bruno

Bruno is an alternative to Postman which offers some key features that immediately appeared useful for our migration activities:

1. User interface

2. Importing collections

3. Assertions

4. Visual Studio Code extension

5. Secrets

User interface

Bruno’s UI is very similar to Postman’s. If you’re used to using Postman, you’ll know straight away where everything is. Postman’s UI was working; it flows, so it seems like Bruno was sticking to that flow.

In Bruno's 'Settings' section, you'll discover a feature that allows you to include scripts for acquiring access tokens or executing other prerequisite actions. Additionally, you can select the authentication mode for the entire collection. Interestingly, this functionality now appears to be absent from Postman's free version, marking a notable advantage for Bruno users.

When it comes to the query section, Bruno closely resembles Postman, with one notable addition: the 'Assertion' section. This extra component provides users with a dedicated space to define assertions, allowing for more comprehensive and efficient testing. We'll delve deeper into this feature later on.

Importing collections

The ability to import existing collections from Postman proved invaluable, particularly given our prior investment in Postman. Using this functionality, we migrated our extensive collection from Postman to Bruno.

However, it's worth noting that some adjustments were necessary during the migration process. Postman’s folder section of pre-script did not get imported, so we had to rewrite it, which we needed to acquire access tokens for our APIs. Additionally, Bruno employs its own set of keywords and conventions, necessitating updates to align our tests to keep them working.

Nevertheless, despite these minor modifications, the migration process was smooth and efficient, enabling us to swiftly transition our testing infrastructure to Bruno's platform without any impact on the validity or functionality of our test suites.

Assertions

As a test engineer, I loved this feature that Postman does not have. It allows users to effortlessly build tests one after another, simplifying the testing process significantly.

Despite my appreciation for this feature, its utilisation was not necessary for our project at the time. Given that we already had an extensive collection established in Postman, our approach involved importing this existing collection into Bruno and subsequently updating it to align with Bruno.

The screenshot below shows Postman’s tests that we imported into Bruno. As you can see, you cannot use them as they are. We updated all our tests using grep which took only a small amount of time to make them executable again.

Visual Studio Code extension

Postman offered an 'export' function, enabling users to work with exported Postman collections in Visual Studio Code. However, the current version has removed this functionality, making it impossible to share collections through Visual Studio Code.

Bruno comes with Visual Studio Extension. What truly set this feature apart was its synchronisation with the UI. Any modifications made within the UI were automatically reflected in the corresponding files. All the essential components, header data, request body, variables, and tests, were neatly organised in one file.

Secrets

Within Bruno’s configuration settings, users have the capability to hide the values of variables designated as sensitive.

This functionality ensures that these values remain safeguarded within the environment settings. Consequently, they are accessible for local usage while being shielded from inadvertent exposure when pushing changes to remote repositories. The ability to hide secret values in this manner provides an added layer of security and compliance, aligning with industry best practices for safeguarding sensitive data.

Did Bruno replace Postman successfully?

The short answer is yes; it did for our project. Bruno was able to do everything Postman did.

The longer answer is that during the initial phases of our migration, we encountered a hurdle in extracting environment variables within our CI/CD pipeline. This posed a significant challenge, as integration with our automated pipeline was crucial for maintaining testing efficiency and workflow continuity.

Fortunately, Bruno's status as a relatively new tool with an engaged community proved to be advantageous. The platform undergoes frequent updates, driven by user feedback and community collaboration. As luck would have it, one of the recent updates addressed the issue we encountered, providing the solution needed to proceed with migrating our Postman collections to Bruno.

In addition, Bruno's user interface proved to be intuitive and user-friendly, particularly for those accustomed to Postman. The integration with a VS Code Extension enabled collaboration and sharing among team members, encouraging more engineers to actively contribute to the collection.

Previously, the responsibility for updating the collection primarily fell on test engineers in our project. However, post-migration developers became more involved in updating the collections alongside their application code changes, as both files resided in the same repository. This shift fostered greater collaboration between developers and test engineers, resulting in a smoother and more efficient testing process.

Following the migration, our API tests continued to run without issues. The increased collaboration between developers and test engineers contributed to the overall success of the migration. Encouraged by the smooth migration and the continuous evolution of Bruno, we recommend you give Bruno a try.

Nearform has curated an impressive array of workshops covering a diverse range of topics

Are you a developer eager to expand your skill set or dive into cutting-edge technologies? Look no further than Nearform's collection of open-source workshops!

With a commitment to promoting learning within the developer community, Nearform has curated an impressive array of workshops covering a diverse range of topics, from backend frameworks like Fastify to security essentials like OWASP Top Ten and everything in between.

Each workshop is designed to combine theoretical knowledge with hands-on practice, ensuring participants gain a comprehensive understanding of the topic at hand. Participants are actively engaged in writing code and running tests to validate their understanding and mastery of the concepts covered.

With solutions readily available, participants can confidently solve each exercise knowing that assistance is just a step away. Let's take a closer look at some of the workshops.

Fastify Workshop

Fastify, a web framework for Node.js, boasts lightning-fast performance and a minimalist design. Nearform's Fastify Workshop provides a comprehensive introduction to building web applications with Fastify. Whether you're a beginner or an experienced developer, this workshop offers valuable insights and hands-on exercises to master Fastify's features and best practices.

Here is an example of an exercise you can find in the workshop:

If need some help, you can find the solution in the source code:

import S from 'fluent-json-schema'

const schema = {
  body: S.object()
    .prop('username', S.string().required())
    .prop('password', S.string().required()),
}

export default async function login(fastify) {
  fastify.post(
    '/login',
    { schema },
    async req => {
      const { username, password } = req.body
      return { username, password }
    },
  )
}

And then you can test it with Postman or Curl:

OWASP Top Ten Workshop

Security is paramount in today's digital landscape, and Nearform's OWASP Top Ten Workshop equips developers with the essential knowledge to identify and mitigate common security vulnerabilities. By exploring the OWASP Top Ten risks, participants learn how to secure their applications and protect against threats effectively.

For example, in this exercise you have to fix a snippet of code with a SQL Injection vulnerability:

import errors from 'http-errors'

async function customer(fastify) {
  fastify.get(
    '/customer',
    {
      onRequest: [fastify.authenticate]
    },
    async req => {
      const { name } = req.query
      const { rows: customers } = await fastify.pg.query(
        `SELECT * FROM customers WHERE name='${name}'`
      )
      if (!customers.length) throw errors.NotFound()
      return customers
    }
  )
}

Let’s fix it by sanitising the user input:

import SQL from '@nearform/sql'
import errors from 'http-errors'

export default async function customer(fastify) {
  fastify.get(
    '/customer',
    {
      onRequest: [fastify.authenticate]
    },
    async req => {
      const { name } = req.query
      const { rows: customers } = await fastify.pg.query(
        SQL`SELECT * FROM customers WHERE name=${name}` // SQL function from @nearform/sql
      )
      if (!customers.length) throw errors.NotFound()
      return customers
    }
  )
}

To make sure you have fixed the vulnerability correctly, you can run npm run verify , which will test that your solutions address the security issue in the code.

GraphQL Workshop

GraphQL has revolutionised the way developers design and query APIs, offering flexibility and efficiency unmatched by traditional RESTful approaches. Nearform's GraphQL Workshop demystifies this powerful technology, guiding developers through the fundamentals of schema design, querying, and optimisation techniques.

Loaders are an amazing feature of GraphQL, in this exercise you will learn how to use them correctly:

And then you can check the solution and run the test:

const pets = [
  {
    name: 'Max'
  },
  {
    name: 'Charlie'
  }
]

const owners = {
  Max: {
    name: 'Jennifer'
  },
  Charlie: {
    name: 'Simon'
  }
}

const schema = `
  type Person {
    name: String!
  }

  type Pet {
    name: String!
    owner: Person
  }

  type Query {
    pets: [Pet]
  }
`

const resolvers = {
  Query: {
    pets() {
      return pets
    }
  }
}

const loaders = {
  Pet: {
    async owner(queries) {
      return queries.map(({ obj: pet }) => owners[pet.name])
    }
  }
}

export { schema, resolvers, loaders }

Node Test Runner Workshop

Testing is an integral part of the software development process, ensuring the reliability and robustness of your applications.

Node.js released an experimental test runner in version 18 and made that test runner stable in version 20, allowing developers to test their applications without the need for external dependencies.

Nearform's Node Test Runner Workshop introduces developers to various testing methodologies and tools, empowering them to write comprehensive test suites and automate testing workflows effectively.

In this slide we explain the difference between a Test Runner and a Testing Framework:

Micro Frontends Workshop

Micro Frontends architecture enables teams to independently develop, deploy, and scale frontend components, fostering agility and collaboration in large-scale projects. Nearform's Micro Frontends Workshop guides developers through the principles and implementation strategies of micro frontend architecture, equipping them with the knowledge to build modular and scalable frontend systems.

React Native Workshop

With the rise of mobile app development, React Native has emerged as a popular framework for building cross-platform applications with JavaScript and React. Nearform's React Native Workshopempowers developers to harness the full potential of React Native, from setting up development environments to building native-quality mobile experiences.

Immerse yourself in Nearform’s workshops

Whether you're diving into backend development, exploring emerging technologies, or fortifying your application's security, Nearform's open-source workshops provide invaluable resources and guidance. Immerse yourself in these workshops, join a vibrant developer community and commence a journey of perpetual learning and advancement.

Here you can find the list to all our workshops.

So, which workshop will you venture into first? Let's embark on this learning journey together!

Enhancing Helm chart security and policy compliance with OPA

Managing Kubernetes applications correctly is as crucial as their development. Helm charts are a pivotal tool for deploying and managing these applications efficiently.

However, ensuring that these deployments are secure and adhere to best practices requires robust oversight. This is where the Open Policy Agent (OPA) plays a vital role by enforcing a set of standardised rules.

Leveraging Conftest for OPA policy enforcement

Conftest is a tool that supports DevOps teams by testing structured configuration data against predefined policies, ensuring configurations are correct prior to deployment. These policies, written in the Rego language from OPA, consist of rules that define the necessary logic to enforce desired behaviours. Together, Conftest and OPA create a powerful ecosystem for automating and managing policy enforcement effectively.

The benefits of integrating OPA with Helm

Integrating OPA with Helm chart development enhances Kubernetes management by automating the validation of the Helm templates. This approach not only addresses the challenges of manual checks, but also mitigates potential inconsistencies as Kubernetes environments scale. OPA's policy-as-code model assures uniform policy application across clusters.

Preparing your environment

To integrate Open Policy Agent (OPA) with Helm, you will need several tools and a basic understanding of key technologies:

1. Helm: Helm installation guide.

2. Conftest: Conftest installation guide.

3. Local Kubernetes cluster: Optionally, use Minikube or Kind for realistic testing and validation of Helm charts.

Additionally, familiarity with writing OPA policies in Rego, understanding Helm chart structures and Kubernetes resource management is important. In essence, what we are trying to achieve with this is to validate the final Kubernetes manifests; thus knowledge of the chart will help to fix issues.

For practical demonstrations, I'll reference the helm-OPA-policy-testing-templates repository on GitHub, which showcases example policies to maintain standards and recommended practices in Kubernetes.

Repository structure

• mars/: Contains the Helm chart that will be tested — “mars” is just a random name for the chart to be tested.

  • templates/: Includes Kubernetes resource templates such as ConfigMaps and Ingresses.

  • chart.yaml: Details the chart version and metadata.

  • values.yaml: Holds default configuration values.

• policy/: Includes OPA policies structured by enforcement type:

  • deny/: Policies that block deployments under specific conditions.

  • violation/: Policies that identify non-adherence to best practices.

  • warn/: Policies that issue warnings for potential issues.

  • helpers/: Common functions used across various policies.

Leveraging helper functions in Conftest

Helper functions in Conftest streamline policy management by consolidating common logic into reusable components. It simplifies policy creation, enhancing clarity and manageability. The helper functions we will use in the upcoming example scenario are in the kubernetes.rego file in the repository. For detailed examples and guidelines on using these functions, please see the helper functions documentation.

Scenario: Enforcing key policies with Conftest

In this example scenario, we'll use Conftest to enforce two key policies for developing our Helm charts. Firstly, we prohibit the use of the 'latest' image tag for all containers to prevent unpredictability in deployments. Secondly, we mandate that all Kubernetes deployments include specific labels to improve management, visibility and recommended best practices.

Prohibiting 'latest' tag policy*:*

package main

import data.kubernetes

name := input.metadata.name

violation[msg] {
    kubernetes.containers[container]
    [image_name, "latest"] = kubernetes.split_image(container.image)
    msg = kubernetes.format(sprintf("%s in the %s %s has an image, %s, using the latest tag", [container.name, kubernetes.kind, image_name, kubernetes.name]))
}

This policy achieves the following:

• kubernetes.containers[container]: Iterates over each container.

• [imagename, "latest"] = kubernetes.splitimage(container.image): Splits the container image string to check if it uses the "latest" tag.

• msg = kubernetes.format(sprintf(...)): Generates a standardised error message if a container uses the "latest" tag, detailing the container's name and the type of Kubernetes object it belongs to.

Enforce recommended labels policy:

package main

import data.kubernetes

name := input.metadata.name

deny[msg] {
    kubernetes.is_deployment
    not kubernetes.required_deployment_labels
    msg = sprintf("%s must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels", [name])
}

This policy does the following:

• kubernetes.is_deployment: Confirms the resource is a Kubernetes deployment.

• not kubernetes.requireddeploymentlabels: Condition checks whether the deployment is missing the necessary labels. The requireddeploymentlabels function, which performs this verification, is defined in the helper functions file.

• msg = sprintf(...): Generates an error message for non-compliant deployments, directing users to a URL with labelling best practices.

How to apply these policies:

Save the policies in a .rego file within a "policy" folder. Conftest defaults to searching for rules in a directory named "policy." To specify a different location, use the --policy or -p flag when running tests.

Run the following command from the root of your repository to test Helm charts against the defined OPA policies:

helm template mars | conftest test -p policy/ -

This command sequence ensures your Helm chart configurations comply with OPA policies before deployment:

• helm template mars: Generates Kubernetes YAML files from the mars Helm chart.

• | (pipe): Passes the YAML output to the next command.

• conftest test: Uses Conftest to evaluate the YAML files against the policies in the policy/ directory.

• -p policy/: Specifies the directory where the policy files are located.

• -: Indicates that Conftest should read input from the standard input (stdin), provided by the pipe.

You should see an output similar to the screenshot below, indicating policy enforcement failures:

FAIL - - main - release-name-mars must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels
FAIL - - main - mars in the Deployment nginx has an image, release-name-mars, using the latest tag

This indicates that our Helm charts do not comply with our policies. For example, as highlighted in the _helpers.tpl file, there are missing deployment labels:

'Fig 1: Missing required labels'

Furthermore, in the values.yml file, it appears that no specific image tag is defined, which defaults to using the "latest" tag:

'Fig 2: Undefined specific image tag'

To align our Helm charts with the policies, we need to define the deployment labels in accordance to what the policy expects, and specify an image tag. We will now update the respective files, as highlighted in the images below:

‘Fig 3: Defined required labels’

‘Fig 4: Image with a specific tag’

After implementing these fixes, rerunning the command helm template mars | conftest test -p policy/ - should not yield any policy failures.

Conclusion

This blog has highlighted the benefits of integrating Open Policy Agent (OPA) with Helm chart development to safeguard Kubernetes deployments. By enforcing standardised policies using Conftest and OPA, teams can ensure their Helm charts meet high security and compliant standards. Moreover, DevOps teams can integrate this mechanism into their GitOps workflow to streamline template validation and necessary security checks, embedding them directly into the deployment process.

Discover how Nearform's Gen AI innovations are revolutionising business data management and automation

At Nearform, we engage with the latest technological trends and innovations. A key focus for us is on Generative AI (GenAI), a technology that's transforming how businesses create and handle information. We're actively exploring its potential, particularly in using machine learning to create new content, such as text, images and even code.

This technology is already revolutionising how businesses handle information, and we've been at the forefront of its application. We're constantly exploring new ways to leverage it to empower our clients and unlock the hidden potential within their data.

Generative AI utilises advanced algorithms to create new content, translating to a wealth of benefits for companies. Imagine instantly summarising complex documents, extracting key insights from vast datasets, or generating creative content tailored to specific needs. This opens doors to improvements in efficiency, data-driven decision-making and a whole new level of automation.

Our solution: The pgRAG AI accelerator library

With pgRAG, Nearform is pushing the boundaries of Generative AI, solving common challenges faced by developers and streamlining AI implementation. We've seen GenAI’s transformative power firsthand across numerous client projects. However, we noticed recurring challenges – developers often needed to reinvent the wheel for common GenAI use cases. This sparked the creation of pgRAG, our in-house AI accelerator library.

How does pgRAG work?

The pgRAG library excels in text analysis and summarisation, supporting various document formats like PDFs, Word documents and PowerPoint presentations. It employs cutting-edge natural language processing techniques to perform semantic searches and extract critical information seamlessly. It leverages advanced natural language processing techniques to perform semantic searches and extract key information from PDFs, Word documents, PowerPoint presentations and more.

One of the core features is the ability to generate concise summaries that capture the essence of the document's content. To ensure accuracy, the library employs carefully designed prompts during the summarisation process, mitigating the risk of hallucinations or factual inconsistencies that can sometimes occur with Generative AI models.

What sets pgRAG apart is its capability to analyse and interpret visual elements within documents, such as charts, graphs and images. The AI can extract insights from these visual representations and incorporate them into the overall document summary, providing a more comprehensive understanding of the content.

For instance, when processing a complex financial report, pgRAG can analyse both the textual data and accompanying visualisations like charts and graphs. It then generates a concise summary that captures the key points from the text and insights from the visual elements, presenting decision-makers with a holistic overview of the report.

JavaScript Copy to clipboard

// configuration
const model = new OpenAI{...});
const embeddings = new OpenAIEmbeddings({...});
const dbPool = new pg.Pool({...});

// read the document file
const myDocument = fs.readFileSync('research_paper.pdf');

// initialize pgRag
const pgRagInstance = await PgRag.init({
  embeddings,
  model,
  dbPool
});

// process the document 
const jobId = await pgRagInstance.processDocument({
  data: myDocument, 
  name: 'research_paper.pdf'
});

// document searching
const response = await pgRagInstance.rag({
  prompt: 'Tell me about molecular structure of glucose'
});
console.log('Search response', response);

/* Response example
{
    "response": "C6H12O6 is the molecular formula for glucose. Glucose is a monosaccharide, or simple sugar, that is made from 6 carbons atoms, 12 hydrogen atoms, and 6 oxygen atoms.",
    "documents": [
        {
          "name": "research_paper.pdf",
          "raw_content": "...",
          "content": "...",
          "summary": "...",
          "metadata": "{...}"
        },
        {
          "name": "chemistry_101.pdf",
          "raw_content": "...",
          "content": "...",
          "summary": "...",
          "metadata": "{...}"
        }
    ]    
}
*/

Data privacy and security

At Nearform, data privacy and security are paramount. We implement robust measures to protect sensitive information throughout the entire processing pipeline. To ensure the confidentiality and integrity of data processed by the library, Nearform employs several robust measures:

1. Data encryption: All data, including documents and their summaries, are encrypted both in transit and at rest. This prevents unauthorised access and ensures that data is secure throughout the processing pipeline.

2. Anonymisation techniques: When processing documents, any personally identifiable information (PII) is anonymised to protect individual privacy.

3. Regular audits: The library undergoes regular security audits to identify and mitigate potential vulnerabilities, ensuring continuous improvement in data protection practices.

4. Prompt design: As mentioned, the library uses carefully crafted prompts to prevent hallucinations, which also plays a role in avoiding the generation of sensitive information that isn't present in the source documents.

By integrating these practices, Nearform demonstrates its commitment to safeguarding user data, ensuring that the pgRAG library is not only powerful and efficient but also trustworthy and secure.

Conclusion

By harnessing the transformative power of Generative AI, Nearform is not just empowering businesses – we're revolutionising the way they utilise their data. Our AI accelerator library, pgRAG, simplifies the integration process, making this cutting-edge technology accessible to a wider audience. Leveraging state-of-the-art natural language processing (NLP) techniques and large language models (LLMs), pgRAG offers powerful text analysis, summarisation, and generation capabilities across various document formats.

Currently, pgRAG is an internal tool within Nearform, but we are actively exploring the possibility of releasing it as an open-source project in the future. This would allow the broader developer community to contribute to its development and leverage its capabilities for their own applications.

At Nearform, we are committed to the responsible and ethical use of AI technologies, ensuring that our solutions prioritise data privacy, security and accuracy.

We're excited to see how GenAI technology continues to evolve and transform the way we work. Our team is actively researching and developing new techniques to improve the accuracy, efficiency and scalability of our AI accelerator library.

Stay tuned for more updates from the Nearform team as we continue to explore and push the boundaries of AI technology. Together, we're shaping the future of business innovation.

We explore GraphRAG by implementing it in a JavaScript application

Generative AI (GenAI) is emerging as a powerful technology across tech industries. It is used to generate text responses for user prompts or questions and is based on large language models (LLMs) trained on massive data resources.

Training LLMs is an expensive process, making regular training with up-to-date data impractical. Consequently, LLM knowledge is often outdated. With that being said, a common issue with LLMs is their occasional tendency to provide incorrect responses.

Retrieval-Augmented Generation (RAG) is an approach that can solve this problem by enabling LLMs to access additional data resources without requiring retraining, resulting in better answers. An even more effective approach is GraphRAG, which can provide more accurate answers and is essentially an extension of RAG.

In this blog post, we will explore GraphRAG by implementing it in a JavaScript application. We drew inspiration from a LangChain blog post, which explores GraphRAG with a Python application. LangChain is a framework for building applications based on LLMs. It provides tools and abstractions to improve the customisation, accuracy, and relevancy of the information generated by the models. We will be using LangChain JS framework in the application demonstrated in this blog post.

What is RAG?

Before delving into GraphRAG, let's first understand what RAG is. RAG is an AI technique that can enhance the quality of GenAI by enabling LLMs to access additional data without the need for retraining.

It offers a method for optimising the output of an LLM with targeted information without modifying the underlying model itself. This means that the RAG approach in GenAI can provide more contextually appropriate answers based on current data.

Typically, RAG implementations require vector databases that enable rapid storage and retrieval of data fed into the LLM.

What is GraphRAG?

GraphRAG is an extension of RAG where a graph database is used alongside a vector database to store and retrieve data. Vector databases excel in handling unstructured data, but they cannot efficiently store interconnected and structured information. That's where a graph database comes into play.

The concept behind GraphRAG is to harness the structured nature of data to enrich the depth and contextuality of retrieved information. Graph databases organise data into nodes and relationships, aiding LLMs in better understanding the data and providing more accurate answers.

As GraphRAG extends RAG, we can integrate structured data obtained from the graph database with unstructured data obtained from the vector database and then input it into the LLM. The model can thus utilise both structured and unstructured data to generate improved responses. In our demonstration, we will be using a Neo4j database to store both structured and unstructured data.

Now that we understand what RAG and GraphRAG are, let's build an application that demonstrates this.

The application consists of two parts: the loader and the retriever.

1. The loader fetches the source content from a knowledge base and stores the data in the Neo4j database.

2. The retriever fetches data from the Neo4j database and feeds it into the LLM to obtain responses. The retriever runs on demand whenever a question or prompt is sent.

The code for the application explained in this blog post is available on GitHub.

Environment setup

In our application, alongside LangChain and Neo4j, we will be using OpenAI. So let’s set these up first.

There are two options for setting up a Neo4j database. The easiest option is to use Neo4j Aura, which offers a free instance of the Neo4j database. The other option is to set up a local instance of the Neo4j database by downloading the Neo4j Desktop application and creating a local database instance.

Once the Neo4j database instance is ready, we will have the URI, username, and password of the database instance. We also need an OpenAI API key to use their LLM models. Set this data in environment variables so that the application can read it from there.

const url = process.env.NEO4J_URI
const username = process.env.NEO4J_USERNAME
const password = process.env.NEO4J_PASSWORD
const openAIApiKey = process.env.OPENAI_API_KEY

Loader

Let's dive into the coding part of the loader.

We will first initialise the LLM by creating an instance of ChatOpenAI. We will pass a couple of parameters to set the temperature and the LLM model along with the OpenAI API key.

For our scenario, where we want the LLM to respond based on the stored knowledge base, there isn’t a need for the LLM to be creative. So let’s set the temperature to 0 to ensure we get deterministic outputs.

There are a bunch of LLMs offered by OpenAI. The gpt-4-turbo model is the most recent version at the time of writing this article. It is trained with data up to December 2023 and is more capable and reliable. However, we will be using gpt-3.5-turbo as it is relatively cheaper and sufficient for our demonstration.

Also, let’s initialise the Neo4jGraph database.

const llm = new ChatOpenAI({
  temperature: 0,
  modelName: 'gpt-3.5-turbo',
  openAIApiKey
})

const graph = await Neo4jGraph.initialize({ url, username, password })

Then, load the source text content from a knowledge base. In our application, we will use the IMSDBLoader provided by LangChain to retrieve text content. LangChain offers a variety of text loaders that allow us to easily fetch text content from various web resources.

The IMSDBLoader is one such loader provided by LangChain, enabling us to fetch content from IMSDb, a website where movie scripts can be found.

We will retrieve data from just one page (the script of the movie The Avengers) on IMSDB. The load method of the loader will return an array of documents (one document per page). Since we are loading only one page in our example below, the length of the returned array will be 1.

const loader = new IMSDBLoader(
  '<https://imsdb.com/scripts/Avengers,-The-(2012).html>'
)
const rawDocs = await loader.load()

Now that we have the raw text content loaded, let’s split it into multiple smaller chunks. LangChain provides several text splitters that enable us to divide long documents into smaller segments. We will utilise the TokenTextSplitter utility class for chunking, specifying only the chunk size and the chunk overlap size in bytes.

Next, we will iterate over the returned list of chunks and create a new list with Document objects for each chunk.

const textSplitter = new TokenTextSplitter({
  chunkSize: 512,
  chunkOverlap: 24
})

let documents = []
for (let i = 0; i < rawDocs.length; i++) {
  const chunks = await textSplitter.splitText(rawDocs[i].pageContent)
  const processedDocs = chunks.map(
    (chunk, index) =>
      new Document({
        pageContent: chunk,
        metadata: {
          a: index + 1,
          ...rawDocs[i].metadata
        }
      })
  )
  documents.push(...processedDocs)
}

The next step is to convert the list of documents into a list of graph documents. LangChain offers an LLMGraphTransformer class, which performs this conversion for us. Graph Documents comprise a blend of structured and unstructured data. Structured data is represented as nodes and relationships, while unstructured data is the actual source text content.

LLMGraphTransformer utilises the LLM to determine the nodes and relationships for a given text document.

const llmTransformer = new LLMGraphTransformer({ llm })
const graphDocuments = await llmTransformer.convertToGraphDocuments(documents)

Save the Graph Documents to the Neo4j database using the addGraphDocuments method.

await graph.addGraphDocuments(graphDocuments, {
  baseEntityLabel: true,
  includeSource: true
})

The loader part is pretty simple, as you can see above. We loaded the source content from the IMSDB loader and then split the content into smaller chunks. Next, we converted the text chunks into graph documents with the help of LLMGraphTransformer and stored them in the Neo4j database.

Now that the loader code is ready, give it a try by running it. You should see the graph documents for the passed source content saved successfully in the Neo4j database.

Retriever

Let's dive into the coding part of the retriever. We will start by initialising the LLM and the Neo4jGraph database, just as we did in the loader.

Next, we need to initialise the Neo4j vector store, which we will use to fetch the unstructured data stored in the loader part. We will accomplish this by invoking the fromExistingGraph static method of Neo4jVectorStore, which returns a handle to the database. We will use this handle later in the application to fetch the unstructured text data.

const neo4jVectorIndex = await Neo4jVectorStore.fromExistingGraph(
  new OpenAIEmbeddings({ openAIApiKey }),
  {
    url,
    username,
    password,
    searchType: 'hybrid',
    nodeLabel: 'Document',
    textNodeProperties: ['text'],
    embeddingNodeProperty: 'embedding'
  }
)

The next step is to define a chain that enables us to extract entities from a given string or question.

In LangChain, chains represent sequences of calls — whether to an LLM, a tool, or a data preprocessing step. In our application, we will use chains to deliver prompt templates and inputs to the LLM to obtain generated data.

An entity is essentially an object or thing that exists in the real world. For example, in the question "Who is Tony Stark?", "Tony Stark" is an entity. There could be more than one entity in a given string as well. For example, in the question "How are Thor and Loki related?", "Thor" and "Loki" are entities.

In the following code, we are defining a prompt template that instructs the LLM to extract entities from the passed question. Additionally, we are defining the output schema, which specifies the structure of the output we require — a list of entities.

The entity chain is created by passing the prompt, output schema, and the LLM to the createStructuredOutputRunnable function. When the entity chain is invoked, the prompt and the output schema are fed to the LLM, which extracts and returns the entities.

const entitiesSchema = z
  .object({
    names: z
      .array(z.string())
      .describe(
        'All the person, organization, or business entities that appear in the text'
      )
  })
  .describe('Identifying information about entities.')

const prompt = ChatPromptTemplate.fromMessages([
  [
    'system',
    'You are extracting organization and person entities from the text.'
  ],
  [
    'human',
    'Use the given format to extract information from the following input: {question}'
  ]
])

const entityChain = createStructuredOutputRunnable({
  outputSchema: entitiesSchema,
  prompt,
  llm
})

Next, let's execute a Neo4j query to create a full-text index — if it doesn’t already exist. A full-text index is utilised to index nodes and relationships, enabling querying of nodes later in the application.

This query will create the index when you run the retriever for the first time. It won’t perform any actions in subsequent runs.

await graph.query(
  'CREATE FULLTEXT INDEX entity IF NOT EXISTS FOR (e:__Entity__) ON EACH [e.id]'
)

Then, let’s define a structured retriever function that invokes the entity chain to extract entities from the question. For each entity, it executes a query to fetch matching nodes and relationships from the Neo4j database.

async function structuredRetriever(question) {
  let result = ''
  const entities = await entityChain.invoke({ question })

  for (const entity of entities.names) {
    const response = await graph.query(
      `CALL db.index.fulltext.queryNodes('entity', $query, {limit:2})
      YIELD node,score
      CALL {
        MATCH (node)-[r:!MENTIONS]->(neighbor)
        RETURN node.id + ' - ' + type(r) + ' -> ' + neighbor.id AS
        output
        UNION
        MATCH (node)<-[r:!MENTIONS]-(neighbor)
        RETURN neighbor.id + ' - ' + type(r) + ' -> ' +  node.id AS
        output
      }
      RETURN output LIMIT 50`,
      { query: generateFullTextQuery(entity) }
    )

    result += response.map(el => el.output).join('\\n') + '\\n'
  }

  return result
}

Now we can define the final retriever function. It takes the question as input and then retrieves the structured and unstructured data for the passed question. The structured data is fetched from the structuredRetriever we have defined above, and the unstructured data is retrieved from the vector index.

async function retriever(question) {
  console.log('Standalone Question - ' + question)
  const structuredData = await structuredRetriever(question)

  const similaritySearchResults =
    await neo4jVectorIndex.similaritySearch(question)
  const unstructuredData = similaritySearchResults.map(el => el.pageContent)

  const finalData = `Structured data:
  ${structuredData}
  Unstructured data:
  ${unstructuredData.map(content => `#Document ${content}`).join('\\n')}
      `
  return finalData
}

The code we have written so far covers data retrieval from the database for a given question. Now let’s implement a few chains and link them together to make the entire process work.

In our application, we aim to maintain the context of the conversation to ensure continuity between questions. For instance, a user might ask, "Who is Tony Stark?" and then follow up with, "Does he own the Stark Tower?" In this scenario, the LLM needs to comprehend who "he" refers to in the context of the conversation to generate the correct response.

We will define a standalone chain that can understand the context based on the conversation history and then return a new question with the ambiguous parts resolved. In the example provided, when "Does he own the Stark Tower?" is asked, the chain will determine the context with the assistance of the conversation history and return a standalone question: "Does Tony Stark own the Stark Tower?".

const standaloneTemplate = `Given the following conversation and a follow up question, rephrase the follow up question to be a standalone question.
Chat History:
{conversationHistory}
Follow Up Input: {question}
Standalone question:`

const standalonePrompt = PromptTemplate.fromTemplate(standaloneTemplate)

const standaloneQuestionChain = standalonePrompt
  .pipe(llm)
  .pipe(new StringOutputParser())

Then, we will define a retriever chain that retrieves context (structured and unstructured data) from the database for the generated standalone question by invoking the retriever function we implemented above.

const retrieverChain = RunnableSequence.from([
  prevResult => prevResult.standaloneQuestion,
  retriever
])

Now, let’s define a chain that can generate the final response based on the context and the original question.

const answerTemplate = `You are a helpful and enthusiastic support bot who can answer any question based on the context provided and the conversation history. Try to find the answer in the context. If the answer is not given in the context, find the answer in the conversation history if possible. If you really don't know the answer, say "I am sorry, I don't know the answer to that.". And don't try to makeup the answer. Always speak as you are chatting to a friend

context:{context}
question: {question}
answer:`

const answerPrompt = PromptTemplate.fromTemplate(answerTemplate)

const answerChain = answerPrompt.pipe(llm).pipe(new StringOutputParser())

Finally, let’s connect the above three chains into a single sequential chain. The idea is to first invoke the standalone chain to obtain the standalone question, then invoke the retriever chain to acquire the context, and finally feed the question and context to the answer chain to generate the final response.

const chain = RunnableSequence.from([
  {
    standaloneQuestion: standaloneQuestionChain,
    orignalInput: new RunnablePassthrough()
  },
  {
    context: retrieverChain,
    question: ({ orignalInput }) => orignalInput.question,
    conversationHistory: ({ orignalInput }) => orignalInput.conversationHistory
  },
  answerChain
])

Now let's ask our questions one after the other by invoking the final chain. Additionally, we can capture each of the responses into an array to maintain the conversation history.

const conversationHistory = []

function logResult(result) {
  console.log(`Search Result - ${result}\\n`)
}

async function ask(question) {
  console.log(`Search Query - ${question}`)
  const answer = await chain.invoke({
    question,
    conversationHistory: formatChatHistory(conversationHistory)
  })
  conversationHistory.push(question)
  conversationHistory.push(answer)
  logResult(answer)
}

await ask('Loki is a native of which planet?')
await ask('What is the name of his brother?')
await ask('Who is the villain among the two?')
await ask('Who is Tony Stark?')
await ask('Does he own the Stark Tower?')

Below are the answers returned by the LLM for each of the questions asked.

Search Query - Loki is a native of which planet?
Standalone Question - What planet is Loki a native of?
Search Result - Loki is a native of Asgard.

Search Query - What is the name of his brother?
Standalone Question - What is the name of Loki's brother?
Search Result - His brother's name is Thor.

Search Query - Who is the villain among the two?
Standalone Question - Which of the two, Loki and Thor, is considered the villain?
Search Result - The villain is Loki.

Search Query - Who is Tony Stark?
Standalone Question - Who is Tony Stark?
Search Result - Tony Stark is a character who is also known as Iron Man. He is a genius engineer, industrialist, and philanthropist who uses his suit of armor to fight crime and protect the world.

Search Query - Does he own the Stark Tower?
Standalone Question - Does Tony Stark own the Stark Tower?
Search Result - Yes, Tony Stark owns the Stark Tower.

As you can see, our application was able to generate standalone questions based on the context of the conversation and also returned the correct responses for each of them.

Conclusion

To summarise what we have covered in this blog post, we implemented a loader module that fetches raw text data from a web source, converts it into graph documents, and stores it in the Graph database. Next, we implemented a retriever module that takes a user's question, extracts entities from it, retrieves both structured and unstructured data related to the entities and the question, and feeds this data to the LLM model to generate an answer.

GraphRAG greatly benefits businesses by improving customer service through precise and relevant interactions. For industries relying on extensive knowledge bases, the ability to generate accurate information can streamline processes, reduce errors, and enhance decision-making. Additionally, the adaptive nature of GraphRAG allows businesses to tailor responses based on specific contextual needs, providing a more personalised and efficient user experience. Ultimately, the integration of GraphRAG can give businesses a competitive advantage in an ever-evolving digital landscape.

References

Here are some interesting blog posts that will help expand your understanding of GraphRAG:

• GraphRAG: Unlocking LLM discovery on narrative private data

• Neo4j Integrates with Microsoft to Evolve Data Analytics and Enhance GenAI

As Node.js continues to evolve, Milo stands ready to facilitate seamless HTTP communication

The Hypertext Transfer Protocol (HTTP) stands as one of the oldest and most critical protocols in daily internet usage. Ensuring a solid and performant implementation of this protocol is fundamental for both user satisfaction and developer efficiency.

Let's explore how Node.js tackles this task and introduces Milo, a promising replacement for the current HTTP parser, llhttp.

A journey through HTTP versions

Originating in 1991 with HTTP/0.9, the HTTP protocol has evolved over the years. Despite its age, only three main versions exist today:

1. HTTP/1.1: The most widely used version, defined in RFC 9112.

2. HTTP/2.0: An evolution built upon SPDY, aiming to address TCP protocol limitations, detailed in RFC 9113.

3. HTTP/3.0: The latest iteration, based on QUIC, ushering HTTP over UDP for the first time. Defined in RFC 9114.

While HTTP/0.9 and HTTP/1.0 remain widely used, they never achieved RFC standardisation and are now considered obsolete. The current version of the procotols instead share common semantics in RFC 9110.

Node.js currently supports HTTP/1.1 and, to some extent, HTTP/0.9 and HTTP/1.0 via its http and https modules. Although HTTP/2.0 is supported through the http2 module, active development is halted due to the relatively low adoption rate and the emergence of HTTP/3.0.

The state of HTTP parsing in Node.js

Presently, Node.js employs the llhttp parser, replacing its predecessor, http_parser, due to performance and maintainability issues. Developed by Fedor Indutny in 2019, llhttp operates by specifying parsing rules in TypeScript, transpiling them into a high-performance parser in C using llparse. In the image below you can see a visual representation of llhttp state machine.

llhttp is the default Node.js parser since version 12.0.0. Additionally, llhttp has an extensive test suite, partially inherited by http_parser, which is executed by transpiling Markdown files to C and then execute them.

Despite its efficiency, llhttp suffers from a lack of documentation of its unique architecture, posing challenges for maintenance, evolution and security.

Introducing Milo: A modern HTTP parser

In response to the limitations of llhttp, Paolo Insogna started Milo in 2023 — a new HTTP parser written in Rust. Milo retains a state-based architecture akin to llhttp but leverages Rust's powerful procedural macros to define states, resulting in more readable and maintainable code.

For instance, the snippet below is an actual Milo state definition.

state!(request_protocol, {
  match data {
    string!("HTTP/") | string!("RTSP/") => {
      callback!(on_protocol, 4);
      parser.position += 4;

      move_to!(request_version, 1)
    }
    otherwise!(5) =>
      fail!(UNEXPECTED_CHARACTER, "Expected protocol"),
    _ => suspend!(),
  }
});

The programming language above is Rust.

When waiting for the protocol, which follows the URL in first line of the request (example: GET /home HTTP/1.1), the parser will try to match the current data with three possible cases:

1. If it starts with HTTP/ or RTSP/ , then it will invoke the on_protocol callback, will advance the position in the data by 4 characters and then move the parser to the request_version state.

2. Otherwise, if at least 5 characters are available then it will mark the parsing as failed.

3. Otherwise, if not enough characters are available (_ => ...) it will suspend the parsing.

And below is the actual compiled Rust code after the macros have been replaced (which happens at compile time, so no performance penalty).

// This is part of a big "match" statement
STATE_REQUEST_PROTOCOL => {
  match data {
      [72u8,
      84u8,
      84u8,
      80u8,
      47u8,
      ..,
      ]
      | [82u8,
      84u8,
      83u8,
      80u8,
      47u8,
      ..,
      ] => {
          #[cfg(not(target_family = "wasm"))]
          (self.callbacks.on_protocol)(self, self.position, 4);
          self.position += 4;
          self.state = STATE_REQUEST_VERSION;
          self.position += 1;
      }
      [_u0, _u1, _u2, _u3, _u4, ..] => {
          self.fail(ERROR_UNEXPECTED_CHARACTER, "Expected protocol");
          break 'parser;
      }
      _ => {
          not_suspended = false;
          break 'state;
      }
  }
}

The programming language above is Rust.

Even with limited Rust knowledge, it's relatively simple to map statements between the two snippets.

Using the macros and an eager approach, Milo was able to reduce the number of states to around 30 (while llhttp has around 80).

Unlike llhttp, Milo strictly parses only HTTP/1.1, reducing complexity and chances of introducing vulnerabilities.

How to utilise Milo

Milo offers three implementations: Rust, native (C++, via cbindgen), and WebAssembly (JavaScript). While the Rust implementation is straightforward, the native and WebAssembly versions provide flexibility across different platforms, ensuring compatibility with Node.js environments.

Regardless of the language, Milo ensures a consistent developer experience. The code below shows a sample parsing procedure in Rust with Milo.

use core::ffi::c_void;
use core::slice;
use milo::Parser;

fn main() {
  // Create the parser.
  let mut parser = Parser::new();

  // Prepare a message to parse.
  let message = String::from("HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nabc");
  parser.context = message.as_ptr() as *mut c_void;

  // Milo works using callbacks, All callbacks have the same signature.
  parser.callbacks.on_data = |p: &mut Parser, from: usize, size: usize| {
    let message = unsafe {
      std::str::from_utf8_unchecked(slice::from_raw_parts(p.context.add(from) as *const u8, size))
    };

    // Do something with the informations.
    println!("Pos={} Body: {}", p.position, message);
  };

  // Now perform the main parsing using milo.parse.
  parser.parse(message.as_ptr(), message.len());
}

The programming language above is Rust.

When executed via cargo run, it outputs the following:

Pos=38 Body: abc

The code snippet below shows its equivalents in C++:

#include "milo.h"
#include "stdio.h"
#include "string.h"

int main() {
  // Create the parser.
  milo::Parser* parser = milo::milo_create();

  // Prepare a message to parse.
  const char* message = "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nabc";
  parser->context = (char*) message;

  // Milo works using callbacks, All callbacks have the same signature.
  parser->callbacks.on_data = [](milo::Parser* p, uintptr_t from, uintptr_t size) {
    char* payload = reinterpret_cast<char*>(malloc(sizeof(char) * size));
    strncpy(payload, reinterpret_cast<const char*>(p->context) + from, size);
    printf("Pos=%lu Body: %s\n", p->position, payload);
    free(payload);
  };

  // Now perform the main parsing using milo.parse. 
  // The method returns the number of consumed characters.
  milo::milo_parse(parser, reinterpret_cast<const unsigned char*>(message), strlen(message));

  // Cleanup used resources.
  milo::milo_destroy(parser);
}

The programming language above is C++.

And JavaScript:

import { milo } from "@perseveranza-pets/milo";

// Prepare a message to parse.
const message = Buffer.from("HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nabc");

// Allocate a memory in the WebAssembly space. 
// This speeds up data copying to the WebAssembly layer.
const ptr = milo.alloc(message.length);

// Create a buffer we can use normally.
const buffer = Buffer.from(milo.memory.buffer, ptr, message.length);

// Create the parser.
const parser = milo.create();

// Milo works using callbacks, All callbacks have the same signature.
milo.setOnData(parser, (p, from, size) => {
  console.log(
    `Pos=${milo.getPosition(p)} Body: ${message
      .slice(from, from + size)
      .toString()}`
  );
});

// Now perform the main parsing using milo.parse. 
// The method returns the number of consumed characters.
buffer.set(Buffer.from(message), 0);
const consumed = milo.parse(parser, ptr, message.length);

// Cleanup used resources.
milo.destroy(parser);
milo.dealloc(ptr, message.length);

What lies ahead for Milo and Node.js?

Milo is currently feature-complete, boasting superior performance in its native version. However, optimisation efforts are underway for the WebAssembly version, which is the one targeted for Node.js integration. Once performance issues are resolved, Milo aims to replace llhttp, bringing Node.js in a new era of HTTP parsing characterised by robustness, performance, and maintainability. As Node.js continues to evolve, Milo stands ready to facilitate seamless HTTP communication, empowering developers to build efficient and reliable web applications.

Understand how to do a real-time data replication in Postgres with Node.js

In today's fast-paced digital landscape, businesses rely heavily on data to drive decision-making processes. Real-time data replication has emerged as a critical capability for organisations seeking to stay ahead of the curve, enabling them to synchronise data across multiple databases seamlessly.

To make a few practical examples, real-time data replication is essential for scenarios such as:

• Keeping different databases in sync, which is a typical scenario when a company acquires another company and needs to merge the data.

• Relying on a database to trigger events in other systems; for example, when a new user is created in the database, a welcome email is sent without modifying existing code or introducing new architecture components like message queues.

• Keeping an application's in-memory cache in sync with the database to improve the performance of read queries.

• For high availability and disaster recovery scenarios.

As you can see, real-time data replication is a powerful tool that can be used in various scenarios to improve the performance, reliability and scalability of your applications.

In this blog post, we'll explore the power of Postgres replication management, to understand how to do a real-time data replication in Postgres with Node.js.

You will need to run some Docker commands to set up a Postgres instance with logical replication enabled, but it is a copy-paste operation.

Editor’s note: This is a cross-post written by Senior Software Developer, Manuel Spigolon. Manuel has his own blog at backend.cafe where you can subscribe for updates and find more great posts. Some of the links in the article point to Manuel’s personal GitHub account.

Introduction to Postgres replication management

PostgreSQL is a powerful open-source relational database system known for its robust features and extensibility. One of its standout capabilities is replication management, allowing you to replicate data from one database to another in real-time. This feature is invaluable to organisations that require characteristics such as:

• High availability: the primary database fails, and a standby server takes over seamlessly.

• Load balancing: distributing read queries across multiple replicas to improve performance.

• Data distribution: synchronising data across geographically distributed systems.

Postgres offers various mechanisms to support the listed scenarios where each solution has its strengths and use cases. To list a few:

• Synchronous multimaster replication: a query must be committed on all nodes before returning to the client. Very high availability and data consistency but with a performance cost.

• Write-ahead Log Shipping (WAL): the primary server sends WAL segments to standby servers, which replay them to stay in sync. It's a simple and reliable solution but with a potential for data loss.

• Logical Replication: replicates individual changes (inserts, updates, deletes) rather than entire WAL segments. It's suitable for scenarios such as data warehousing, data distribution and selective replication. Moreover, it allows for more granular control over which tables and changes are replicated and it is possible to replicate data between different versions of Postgres or multiple sources!

The complete list of replication mechanisms can be found in the Postgres documentation.

In this blog post, we'll focus on Logical Replication mechanism.

The WAL file

The Write-ahead Log (WAL) is a fundamental concept in Postgres replication and we mentioned it in the previous section. The WAL is a file that stores all changes made to the database, such as inserts, updates and deletes, in a sequential manner. We could say that the WAL is our source of truth, and this file is handled by Postgres to guarantee data consistency and durability in case of a crash or disk failure.

We must discuss the WAL because it is the foundation of Postgres replication. We can configure Postgres to handle the WAL file, and we can use it to replicate data across multiple databases. So we must understand the wal_level configuration parameter. This parameter defines how much information is written to the WAL file. The possible values are:

• minimal: only the information needed to recover from a crash is written to the WAL file.

• replica: the default value, it writes enough information to support WAL archiving and replication.

• logical: it stores the same information as replica and additional information needed for logical replication, so this configuration requires more disk space.

Developing a real-time data replication system with Node.js

To develop a real-time data replication system with Node.js, we must follow these steps:

1. Initialise the Postgres database.

2. Create a data producer we want to replicate.

3. Create a data consumer that replicates the data through the Postgres replication mechanism.

So let's start!

Setting up Postgres

We can start our journey into Postgres replication management by starting a Postgres instance and configuring it to support logical replication. Let's use Docker for this task:

docker run \
  --name demo-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=foopsw \
  postgres:16 \
  postgres -c "wal_level=logical"

This command will start a Postgres instance with logical replication enabled, and you can connect to it using the following command:

docker exec -it demo-postgres psql -U postgres

Now, from the Postgres shell, we can create a database and a table to work with:

CREATE TABLE IF NOT EXISTS foo (
  id SERIAL PRIMARY KEY,
  col1 VARCHAR,
  col2 INT
);

To check if the table was created successfully, the following command lists the user's tables in the database:

\dt

Creating a data producer

Now that we have our Postgres instance set up, let's create a Node.js application that acts as a data producer. This application will insert data into the foo table we created earlier and represent the source of data replication. It could be a web application, an IoT device, or any other data source you may have.

Let's create a producer.js file and implement the following logic:

• It connects to the Postgres database.

• Every second, it inserts a new row into the foo table or updates the last inserted row alternatively.

• It listens for a SIGINT signal to gracefully close the connection.

import pg from 'pg' // ℹ️ npm install pg
const { Client } = pg

const client = new Client({
  user: 'postgres',
  password: 'foopsw'
})

await client.connect()

let counter = 0
let lastId = 0
const fakeUserInteraction = setInterval(async () => {
  if (counter % 2 === 0) {
    const res = await client.query('INSERT INTO foo (col1, col2) VALUES ($1, $2) RETURNING id', ['Hello world!', counter])
    lastId = res.rows[0].id
    console.log(`Inserted new row: ${lastId}`)
  } else {
    await client.query('UPDATE foo SET col1 = $1, col2 = $2 WHERE id = $3', ['Hello world!!!', 42, lastId])
    console.log(`Updated row ${lastId}`)
  }

  counter++
}, 1000)

process.on('SIGINT', async () => {
  clearInterval(fakeUserInteraction)
  await client.end()
})

To run this code the node producer.js command is enough.

Creating a data consumer

The data consumer is the other side of the replication process. It can be another Postgres instance, or even a different a different database engine. Postgres allows us to replicate the data seamlessly across different versions of the Postgres database just by configuring them accordingly (not the topic of this blog post, but there are good video tutorials for this use case).

Our use case is to replicate the data to a Node.js application! This application will connect to the Postgres database and listen for changes in the foo table using the logical replication mechanism.

Setting up the data consumer

To set up the data consumer, we must introduce some new Postgres concepts:

• Publication: A publication defines a set of tables and changes to be replicated. We must create a publication to specify which tables and changes are replicated.

• Subscription: A subscription defines the source of replication (e.g., primary server) and the target replica(s). We must create a subscription to subscribe to changes happening in the foo table.

• Replication slot: A replication slot is like a bookmark in the WAL file that keeps track of the last WAL segment read by a client. It forces the primary server to retain the WAL segments required by any client that is using the replication slot.

We need to create all these objects in the Postgres database before we can start listening for changes. Let's do it programmatically with Node.js by creating a setup-consumer.js file:

import pg from 'pg'
const { Client } = pg

const client = new Client({ user: 'postgres', password: 'foopsw' })
await client.connect()

await createPublicationIfNotExists('foo_even', 'TABLE foo WHERE (id % 2 = 0);')
await createPublicationIfNotExists('foo_update_only', "TABLE foo WITH (publish = 'update');")

await client.end()

async function createPublicationIfNotExists (pubName, condition) {
  const pub = await client.query('SELECT * FROM pg_publication WHERE pubname = $1', [pubName])

  if (!pub.rows.length) {
    await client.query(`CREATE PUBLICATION ${pubName} FOR ${condition}`)
    console.log(`Created publication ${pubName}`)
  } else {
    await client.query(`ALTER PUBLICATION ${pubName} SET ${condition}`)
    console.log(`Updated publication ${pubName}`)
  }
}

The code shows how to create and update a publication. When a publication is created, it specifies:

1: Which tables and columns are included in the replication process?

• If no columns are specified, all columns are included.

• It is possible to list multiple tables or set FOR ALL TABLES; to include all tables in the replication process.

2: Which operations are included in the replication process?

• The default is to include all operations (inserts, updates, deletes).

• It is possible to specify only inserts, only updates, or only deletes.

We have created two publications in the code snippet above:

• foo_even: it includes only rows where the id is an even number.

• fooupdateonly: it includes only updates.

As shown, the publications are very flexible and can be tailored to specific use cases.

Subscribing to changes

Finally, we are ready to create the consumer.js file to listen for changes in the foo table. To do so, we will use the postgres module because it provides a simple way to consume the logical replication data changes or we should implement the logical replication protocol ourselves. Alternatively, you can use the pg-logical-replication library — it depends on your preference.

To create the consumer.js file, we can use the following code snippet. So first we must connect to the Postgres database and list all the publications we want to subscribe to:

import postgres from 'postgres'

const sql = postgres({
  debug: true,
  user: 'postgres',
  password: 'foopsw',
  publications: [
    'foo_even',
    'foo_update_only'
  ]
})

Then we can subscribe to the changes happening in the foo table:

const eventPattern = '*:foo'
const { unsubscribe } = await sql.subscribe(
  eventPattern,
  (row, { command, relation, key, old }) => {
    console.log({
      command,
      row
    })
  },

  function onConnect () {
    // Callback on initial connect and potential reconnects
    console.log('Connected to the publication')
  }
)

process.on('SIGINT', async () => {
  await unsubscribe()
  process.exit()
})

If we run the node consumer.js command, we will see the console.log output every time the producer.js:

• Insert a row with an even ID in the foo table.

• Update a row in the foo table.

Note that the eventPattern is just a feature of the postgres module that allows us to filter the changes we are getting from the database. The main driver is and will always be the Postgres publication we created earlier with the setup-consumer.js script.

So far we did not create the Replication Slot, but the postgres module will do it for us by calling the CREATEREPLICATIONSLOT command creating a TEMPORARY slot. Every subscription needs a Replication Slot to track the changes that they are consuming.

Note that the Replication Slot MUST be deleted or consumed by the client, otherwise — if it isn't then the WAL file in the primary server will not be truncated and the disk space will grow indefinitely! Luckily, the postgres module creates a temporary replication slot that is automatically deleted when the connection is closed.

Now our Node.js application is ready to listen for changes in the foo table and replicate them in real-time!

Conclusion

PostgreSQL's replication capabilities are a cornerstone of its reliability and scalability. We just scratched the surface of what is possible with Postgres replication management, but we have seen how to set up a real-time data replication system using Node.js and Postgres logical replication.

Another interesting use case is to use the logical replication mechanism to read all the changes happening in the database while the Node.js application was offline. This is possible by handling the Replication Slot manually and it can be done with the pg-logical-replication module's API, but this will be the topic of another blog post!

We hope this blog post has given you a good starting point to explore Postgres replication management further. Here are some resources to deepen your knowledge:

• https://www.youtube.com/watch?v=WXKxwl9k5Q8

• https://www.youtube.com/watch?v=3Z4Hhh5EnLA

• https://www.youtube.com/watch?v=E6W-ZWVRAHU

Comment and share if you enjoyed this article!

From version numbers to the release lifecycle, we help newcomers get familiar with the Node.js release process

Understanding the Node.js release process might seem tricky at first, especially if you're new or not familiar with all the details. However, mastering it not only makes developers’ lives easier but brings real value to businesses.

Staying up to date not only reduces downtime and boosts software reliability but also minimises the risk of costly, large-scale migrations to newer versions. By constantly updating versions, developers save time that can be better spent on revenue-generating activities. This proactive approach translates into fewer security risks, faster performance and lower cloud costs. Altogether, it keeps businesses competitive, delights users and secures long-term success.

As a maintainer of Node.js, I've recently started serving as a releaser. This role has given me a good understanding of the release schedule, that's why I'm here to shed some light on how it all works.

Odd and even version numbers

It's essential to know that odd-numbered versions serve as a playground for developers.

These versions are active and primarily used by package authors and users to preview upcoming features. Odd-numbered major version releases (v17, v19, v21) will not be promoted to Long-Term Support (LTS).

However, even-numbered versions become LTS releases (v18, v20, v22).

Interestingly, each major LTS version of Node.js is named after an element from the periodic table (v18 Hydrogen, v20 Iron), adding a touch of chemistry to the release process.

Understanding the Node.js release lifecycle

Node.js follows a structured release schedule to ensure stability, compatibility, and longevity of support for its users. Here's a breakdown of how it all unfolds:

1. Current release status

When a major version of Node.js is released, regardless of whether it is even or odd, it enters the Current release status. This phase lasts for six months. During this time, developers and library authors are encouraged to adopt and adapt to the new features and changes introduced in the latest release. It's a period of innovation and experimentation.

2. Active LTS status

After the initial six-month period, odd-numbered releases transition to unsupported status. Even-numbered releases, however, move into Active LTS status. These LTS releases are ready for general use and offer extended support.

This phase typically lasts for one year before entering the Maintenance LTS status.

It’s worth mentioning that odd-version releases will receive security patches before the next even-numbered major enters the Active LTS status.

3. Maintenance LTS status

While in Active LTS status, a Node.js version receives active support, including new features, fixes for critical bugs and security patches. After this period, the version enters Maintenance LTS status which lasts around 18 months, where only fixes for bugs and security patches are released.

4. End of Life (EOL)

Once a Node.js version reaches the end of its Maintenance LTS period, it is considered End of Life (EOL). At this point, it will no longer receive official support or updates from the Node.js project.

Node.js maintains three release lines simultaneously, two of which are LTS versions, one in Maintanance LTS, one in Active LTS, and the third one as Current (either a odd-numbered version or a even-numbered that has not entered Active status yet), ensuring a balance between innovation and stability.

Here is an image of the current status of Node.js releases from the documentation:

Recently, I had the pleasure of contributing to the release of Node.js 22, which has currently entered the Current status, while the v21 version is being dismissed.

When Node v22 enters the Active LTS status, Node v20 enters the Maintanance Mode, and Node v23 is set as Current.

Recommendations for production applications

For production applications, it's crucial to use Node.js versions that are either in Active LTS or Maintenance LTS status. These versions provide a stable and supported environment for your applications, ensuring reliability and that security fixes.

But don't overlook the importance of testing against Current versions, both odd and even, it's an essential step in keeping your production environment robust and up-to-date.

Odd versions of Node.js not only let you experiment with new features before the release of the next LTS version but also provide warnings for upcoming end-of-life deprecations expected in the next LTS release. This gives you ample time to plan and migrate your applications accordingly. On the other hand, even major versions help you ensure that your application won't break and give you time to prepare for changes.

By doing so, you can provide valuable feedback to the Node.js project and identify any potential compatibility issues early on.

Conclusion

In conclusion, navigating the Node.js release process requires a nuanced understanding of its versioning system and lifecycle. From the distinction between odd and even version numbers to the structured phases of Current, Active LTS, Maintenance LTS, and End of Life, each step serves a vital role in balancing innovation with stability.

As Node.js continues to evolve, understanding its release lifecycle empowers developers to make informed decisions, maintain reliable applications, and contribute to the growth of the ecosystem. Embracing this process not only ensures the longevity of your projects but also fosters collaboration and innovation within the Node.js community.

We take a look at Happy Eyeballs, a crucial tool in ensuring seamless connectivity for users

Every day, pretty much everybody takes for granted the incredible amount of work and technology that makes the internet function. Even developers and other technically-minded individuals often overlook or disregard the intricate details and tasks involved in establishing a connection to a remote host. Let's take a look at one of the details, which happens to have a rather fancy name: Happy Eyeballs.

First of all, what is your address?

When an application seeks to establish a connection to a remote host, it typically only has the hostname. A simple verification of this is that you probably have never typed 216.58.205.46 into your browser's address bar.

Upon receiving the connection request, the browser performs a Domain Name System (DNS) query to resolve the IP address corresponding to the hostname. This information is crucial because certain server application optimisations, such as load balancing, rely on it. Each DNS query can receive its own response, enabling the server to efficiently route clients based on factors like load and geographical position.

Once the client receives an IP address, it has all the necessary components to create a socket: source address, source port, destination address, and destination port.

IPv6 is the future

One detail often overlooked is the IP protocol version. The most well-known and widely supported version is IPv4, where addresses are comprised of four numbers ranging from 0 to 255.

IPv4 has been in use since the 1980s and is still the most commonly used version. However, we're running out of IPv4 addresses. IPv4 theoretically supports only 4 billion addresses, but in practice, due to various technical reasons, the number is much lower.

To address this issue, IPv6 was introduced in 1998 as the successor to IPv4. IPv6 offers a staggering number of addresses ($3.8 \cdot 10^{38}$, to be precise) ensuring we'll never run out. Despite gaining traction in recent years, IPv4 remains the preferred choice, especially for Internet Service Providers and router manufacturers.

This preference can pose a problem; if a destination host only exposes an IPv6 address via DNS and your router or ISP isn't properly configured for IPv6, you may be unable to connect. Similarly, if both IPv4 and IPv6 addresses are provided via DNS but the IPv6 address is listed first, some frameworks may attempt only the first address, resulting in connection failures. This was the case for Node.js before version 19.3.0.

Happy Eyeballs

To address the challenges associated with misconfigured IPv6 connectivity stacks, the Happy Eyeballs RFC (Request for Comments) was introduced in 2012. The whimsical name stems from the term "eyeball," which refers to endpoints representing human internet end-users. The RFC aimed to ensure users wouldn't notice any difference when connecting to a host via IPv6 compared to IPv4.

In 2017, a new version of the RFC was released, proposing a clever solution to the connection problem. If a DNS query returns multiple A (IPv4) and AAAA (IPv6) records, the client must sort them in an alternate order: IPv4, then IPv6, then IPv4 again, and so forth. The code snippet below shows how the sorting is currently done in Node.js.

/*
 validAddress is a tuple of two arrays. 
 Each of them contains either IPv4 or IPv6 only.
 The order of the addresses in the array is the same of DNS response.

 If the first address in DNS response contained a IPv4 address, then
 validAddresses[0] will contain IPv4 only, otherwise is the other way round.
*/
const toAttempt = [];
for (let i = 0, l = MathMax(validAddresses[0].length, validAddresses[1].length); i < l; i++) {
  if (i in validAddresses[0]) {
    ArrayPrototypePush(toAttempt, validAddresses[0][i]);
  }
  if (i in validAddresses[1]) {
    ArrayPrototypePush(toAttempt, validAddresses[1][i]);
  }
}

The client then attempts a connection to the first IP and subsequently to the second IP after a short interval. Importantly, the client doesn't wait for a connection attempt to succeed; once any attempt succeeds, the connection is established, and all other attempts are abandoned.

This approach ensures that regardless of how the DNS records are returned, the client will always be able to choose the best-supported stack.

What about Node.js?

As mentioned earlier, Node.js lacked support for Happy Eyeballs until version 19.3.0, when the autoSelectFamily option was added to net.connect (and made the default in Node.js 20). Prior to this, Node.js would only attempt to connect to the first resolved IPs, regardless of the family, resulting in numerous connection failures.

Due to the internals of Node, Happy Eyeballs was implemented in a loose manner. Although there's never more than one connection attempt to a host, addresses are still attempted in alternate order and with a short, configurable timeout (defaulting to 250ms). This ensures adherence to the RFC's core idea, and subsequently, Node.js is able to correctly choose the right IP to establish a connection. The snippet below shows how Node.js handles the connection timeouts during the Happy Eyeballs algorithm.

function internalConnectMultipleTimeout(context, req, handle) {
  debug('connect/multiple: connection to %s:%s timed out', req.address, req.port);
  context.socket.emit('connectionAttemptTimeout', req.address, req.port, req.addressType);

  req.oncomplete = undefined;
  ArrayPrototypePush(context.errors, createConnectionError(req, UV_ETIMEDOUT));
  handle.close();

  // Try the next address, unless we were aborted
  if (context.socket.connecting) {
    internalConnectMultiple(context);
  }
}

Conclusion

Navigating a dual-stack world where IPv4 and IPv6 coexist requires careful handling, especially in resolving host addresses and establishing connections.

Happy Eyeballs, with its intelligent approach to address resolution and connection attempts, serves as a crucial tool in ensuring seamless connectivity for users, irrespective of the underlying IP protocol version.

With its adoption in frameworks like Node.js, the internet continues to evolve, maintaining its accessibility and reliability for all users.

Discover Node.js 22’s exciting new features and improvements

With the release of version 22, Node.js continues to push boundaries and offer developers new tools and enhancements to create powerful and efficient applications. In this blog post, we'll explore some of the exciting features and improvements introduced in Node.js 22.

V8 gets updated to version 12.4

This Node.js version includes an important update of V8 to version 12.4, packed with new features and improvements. Here's what's included in this update:

WebAssembly Garbage Collection

One of the highlights of this release is the introduction of WebAssembly Garbage Collection. This feature enhances memory management for WebAssembly code, leading to improved performance and efficiency in your applications.

Array.fromAsync

Introducing Array.fromAsync, a new method that allows you to asynchronously create arrays from async iterables. Here's a quick example of how you can use it:

async function* asyncIterable() {
  for (let i = 0; i < 5; i++) {
    await new Promise((resolve) => setTimeout(resolve, 10 * i));
    yield i;
  }
}

const array = Array.fromAsync(asyncIterable);
// [0, 1, 2, 3, 4]

Sets method

Several new methods are added to Sets, including union, intersection, and difference. These methods make it easier to manipulate Sets and perform common operations. Check out the following examples:

const lts = new Set([18, 20, 22]);
const nonLts = new Set([17, 19, 21]);

const all = lts.union(nonLts); // all versions [18, 20, 22, 17, 19, 21]

all.intersection(nonLts); // only values contained in both sets [17, 19, 21]

all.difference(nonLts); // only values not contained in both sets [18, 20, 22]

Iterator helpers

These helpers include methods like take, drop, and map, making it easier to manipulate and process iterator values. Here are some examples:

function* fibonacci() {
  let current = 1;
  let next = 1;
  while (true) {
    yield current;
    [current, next] = [next, current + next];
  }
}

// Prints only the first 5 values
for (const n of fibonacci().take(5)) {
   console.log(n);
}

// Takes the first five elements, then drops the first two
for (const n of fibonacci().take(5).drop(2)) {
  console.log(n);
}

// Elevates every number at power of 2
for (const n of fibonacci().map((x) => x ** 2)) {
  console.log(n);
}

require()ing ESM modules

One of the most anticipated features in Node.js 22 is the ability to require ECMAScript modules (ESM) synchronously. With the --experimental-require-module flag, developers can now load ESM modules using require(). This feature addresses a common pain point for developers transitioning from CommonJS to ESM. Package authors can now gradually migrate to ESM without disrupting the user experience or bloating the node_modules directory with duplicated modules.

Exporting a ESM module:

// sum.mjs
export default function sum(a, b) { return a + b }

A ESM module can now be used in a CommonJS module:

// index.cjs
const sum = require('./sum.mjs')
console.log(sum(1,2)) // it works!

node --experimental-require-module index.cjs

It's worth noting that while synchronous ESM graphs offer significant benefits, there are still some edge cases and feature interactions to consider. For example, interactions with other experimental features or scenarios involving cyclic dependencies may require further refinement. However, as an initial iteration of an experimental feature, Node.js 22 lays the groundwork for future improvements and iterations.

WebSocket client

In Node.js 22 the WebSocket client implementation, exported from Undici, is now enabled by default, eliminating the need for external dependencies. This built-in support for WebSockets simplifies the development process and ensures compatibility with modern web standards.

// Create WebSocket connection
const socket = new WebSocket("ws://localhost:8080");

// Connection opened
socket.addEventListener("open", (event) => {
  socket.send("Hello Server!");
});

Package.json script execution

With the new --run flag, developers can now execute scripts directly from the package.json. This experimental feature simplifies the execution of common tasks and workflows defined in the project's package.json, improving the development experience.

The --run flag allows running a specified command from a package.json's "scripts" property. If no specific "command" is provided, it will list all available scripts.

When using --run, node prepends ./node_modules/.bin, relative to the current working directory, to the PATH. This enables the execution of binaries from dependencies.

To execute the test script from package.json in the current folder, simply run:

node --run test

You can also pass arguments to the command. Any argument after -- will be appended to the script:

node --run test -- --verbose

It's important to note that node --run is not designed to replicate the behaviours of npm run or similar commands from other package managers. Instead, it prioritises top performance for common use cases by intentionally limiting certain functionalities:

• It doesn't search for package.json files outside the current folder.

• The .bin or node_modules/.bin paths of folders outside the current folder are not prepended.

• pre or post scripts are not executed alongside the specified script.

• Package manager-specific environment variables cannot be defined.

Stable Watch Mode

Watch Mode, previously an experimental feature, is now considered stable.

For those unfamiliar, Watch Mode is a feature that automatically restarts the Node.js process whenever changes are detected in watched files. This means no more manual restarts or interruptions during development and testing, simply add the --watch flag when starting your Node.js application.

By default, it monitors the entry point file and any required or imported modules. However, you can customise this behaviour using the --watch-path flag to specify specific paths to watch.

For example:

node --watch index.js

And if you want to specify custom paths:

node --watch-path=./src --watch-path=./tests index.js

It's important to note that --watch-path is currently supported only on macOS and Windows. Attempting to use it on unsupported platforms will result in an exception.

Glob and GlobSync

This release introduces glob and globSync functions for pattern matching. Developers can now utilise these functions for matching file paths based on specified patterns.

import { glob } from 'node:fs';

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});

JavaScript Copy to clipboard

import { globSync } from 'node:fs';

console.log(globSync('**/*.js'));

Improved performance with Maglev

The introduction of V8's Maglev Compiler, enabled by default on supported architectures, brings significant performance improvements to short-lived CLI programs.

Maglev follows TurboFan and SparkPlug as the third compiler in the V8 engine's lineup.

TurboFan produces highly optimised machine code, albeit with a longer compilation time compared to SparkPlug, which prioritises compilation speed over optimisation. However, Maglev bridges this gap by generating code that is not only significantly faster than Sparkplug's but also compiled much more swiftly than TurboFan's.

By optimising CPU usage, Maglev enhances the overall efficiency of Node.js applications, resulting in faster execution times and better resource utilisation.

Stream default High Water Mark

In Node.js 22, the default High Water Mark for streams is increased from 16KiB to 64KiB, resulting in a noticeable performance boost. While this change might use a bit more memory, the improvements in speed and efficiency outweigh any downsides, especially for applications handling large amounts of data. This update reflects the increased capabilities of modern machines since Node.js creation, following years of progress and technological advancements.

Deprecations and removals

As part of ongoing maintenance and improvement efforts, Node.js 22 also includes several deprecations and removals aimed at streamlining the codebase and promoting best practices. Notably, a lot of crypto constructors that were not supposed to be public and old util methods have been removed. Developers are encouraged to review the list of deprecations and plan accordingly to ensure compatibility with future releases of Node.js.

Conclusion

Node.js 22 represents another significant milestone in the evolution of the Node.js platform, introducing new features, performance enhancements, and improvements to the development experience.

We encourage you to explore the latest release of Node.js 22 and try these new features.

As always, feedback and contributions from the community play a crucial role in shaping the future of Node.js, so don't hesitate to get involved and share your thoughts and ideas.

Add pagination to your GraphQL schema without the boilerplate

We introduce you to therelay-pagination-directive, a new package from Nearform. This package reduces the boilerplate required to implement cursor-based pagination in GraphQL.

You can add the directive to your schema, tag the fields you wish to paginate and all of the types will be generated for you as well as wrapping your resolver responses to create the Connection model objects. All you need to do is update your data queries.

The benefit of this is it reduces work duplication. This means you have more time to work on revenue-generating tasks, such as designing, developing and delivering new products and features.

The problem

At some point, you’ll need to implement pagination within your GraphQL server. Whether to support a paginated UI function or to enable loading large payloads without crashing your server.

The GraphQL documentation describes the ‘Connection Model’ as the best approach to solving pagination within GraphQL. To implement this we need to make the following changes:

• Create Connection and Edge types for each type we wish to paginate.

• Add first and after args to the schema field (forward only pagination).

• Update your data queries to limit the response size, based on the first value, and filter based on the after value. Ensure your query has a consistent sort order.

• Update the resolvers of each type to return the Connection object. Within this map your dataset to match the Edge type.

This can generate a lot of extra work and 90% of the time you’re replicating the effort for each type you wish to paginate.

Making things easier

If you've used GQL directives before you're ready to use this library. Here's an example of integrating the directive with Mercurius. The functionality of this directive happens within the GraphQL execution, so this should be similar for any provider.

import { connectionDirective } from 'relay-pagination-directive'
import Fastify from 'fastify'
import mercurius from 'mercurius'

const { connectionDirectiveTypeDefs, connectionDirectiveTransformer } =
  connectionDirective()

const typeDefs = `
  type People {
    id: ID!
    name: String!
    type: String!
  }

  type Query {
    people: People @connection // Directive added to the type we wish to 
                              // paginate 
  }
`

const resolvers = {
  Query: {
    people: async (root, { first, after }, { app }) => {
      return app.db.getUsers(first, after)
    },
  },
}

// Include the provided directive type definition along with your
// application types
const schema = makeExecutableSchema({
  typeDefs: [connectionDirectiveTypeDefs, typeDefs],
  resolvers
})

// Apply the directive schema transformer 
const connectionSchema = connectionDirectiveTransformer(schema)

app.register(mercurius, {
  schema: connectionSchema,
  graphiql: true
})

await app.listen({ port: 3000 })

Did you notice how we've decorated the people query with the @connection directive? By adding this and using the connectionDirectiveTransformer to wrap your schema you're ready to paginate your users list.

The @connection directive will take the GQL type it's been applied to and generate the related Connection and Edge for you. Following this example, our generated schema would now look like this.

type PageInfo {
  startCursor: String
  endCursor: String
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
}

type People {
  id: ID!
  name: String!
  type: String!
}

type PeopleEdge {
  node: People!
  cursor: ID!
}

type PeopleConnection {
  edges: [PeopleEdge!]!
  pageInfo: PageInfo
}

type Query {
  people(first: Int!, after: ID): PeopleConnection
}

As well as generating these types for you, the people query resolver will be wrapped so that the existing result will be transformed to match the Connection Model schema. This means your existing resolver response can remain unchanged.

One change you will need to make is updating your database queries to respect the first and after values. You’ll also need to ensure your query sorting will be the same across all page queries. Here is an example of converting a simple ‘get all’ query to support pagination.

/* Original query */
select id, name
from users

/* Updated to support pagination */
select id, name
from users
where id < 10 -- If 'after' is supplied add the where clause to get the next page
order by id desc -- Ensuring consistent ordering
limit 10 -- The 'first' value restricting the response size

Full examples of implementing pagination support are available in the repository

Continuing with the above example, our resolver returns an array of People records. An array response from the resolver is assumed to be a collection of nodes and so the transformed result will look like this:

Modelling multi-edge relationships

Often we need to represent multiple relationships to the same model.

Graph data entity relationship diagram

Within GraphQL, this is done by adding properties to the edge between two nodes. This means we need to create multiple Connections/Edges for the same base type. This is achieved in relay-pagination-directive by supplying a prefix argument when adding the directive to your types.

type Film {
    id: ID!
    name: String!
    release: Int!
  }

  type People {
    id: ID!
    name: String!
    type: String!
    films: Film! @connection(prefix: "PeopleFilm")
  }

  type Cinema {
    id: ID!
    name: String!
    films: Film! @connection(prefix: "CinemaFilm")
  }

  type Query {
    people: [People!]! @connection
    cinemas: Cinema @connection
  }

In this instance, the following types will be generated:

• PeopleEdge and PeopleConnection for Query.people

• PeopleFilmEdge and PeopleFilmConnection for People.films

• CinemaEdge and CinemaConnection for Query.cinemas

• CinemaFilmEdge and CinemaFilmConnection for Cinema.films

As shown above, we have different fields available for the PeopleFilm and CinemaFilm relationships (roles, performance, showTimes etc). So that these properties are added to our generated types, you need to provide their definitions via the configuration object that is passed to the connectionDirective function.

const typeOptionsMap = {
  People: {
    edgeProps: {
      PeopleFilm: {
        roles: '[String!]!',
        performance: 'Int!'
      }
    }
  },
  Cinema: {
    edgeProps: {
      CinemaFilm: {
        price: 'Int1',
        showTimes: 'JSON'
      }
    }
  }
}

const { connectionDirectiveTypeDefs, connectionDirectiveTransformer } =
  connectionDirective(typeConnectionMap)

Generating opaque cursors

GraphQL pagination suggests the use of opaque string values for our cursors. That is a string which holds no referential value when viewed by a user, generally a base64 encoded string. This provides us with flexibility over the server pagination implementation as the value holds no meaning to the consumer.

By default, we will look for an id property on your nodes and use this, along with the name of the GraphQL type, to generate a cursor value. It's possible to use a different property for the cursor value or to provide an encoding function to generate a cursor. It is also possible to skip cursor generation altogether and just use a property value that exists on your objects.

You can decide on the cursor implementation strategy for your application on a per-type basis using the typeOptionsMap configuration object as shown below:

import { encodeCursor, connectionDirective } from 'relay-pagination-directive'

const typeOptionsMap = {
  People: {
    encodeCursor: false, // Don't use any encoding, pick the cursor value from
    cursorPropOrFn: 'otherId' // the 'otherId' property
  },
  Cinema: {
    encodeCursor: true, // the default option
    cursorPropOrFn: 'otherId' // encodeCursor('Cinema', item['otherId'])
  }
  Film: {
    cursorPropOrFn: (type, item) => {
      // Add multiple properties to the cursor to drive
      // multi-value sorting on your DB queries
      return encodeCursor(type, `${item.id}:${item.OtherId}`)
    }
  }
}

const { connectionDirectiveTypeDefs, connectionDirectiveTransformer } =
  connectionDirective(typeOptionsMap)

Providing an accurate "hasNextPage" value

One of the key drivers of pagination is the ability to know whether you should query for another page. In the Connection Model, this is powered by the pageInfo.hasNextPage value. If you choose not to provide this value, then we'll determine the value based on whether the length of returned nodes matches that of the requested page size. This can be effective in situations where you aren't displaying any UI element to indicate there is a next page. In scenarios where this value needs to be more precise, it can be supplied from your resolver.

const resolvers = {
  Query: {
    people: async (root, { first, after }, { app }) => {
      const users = await app.db.getUsers(first + 1, after)
      return {
        edges: users,
        pageInfo: {
          hasNextPage: users.length > first,
        }
      }
    },
  },
}

When an object is returned by a resolver we will merge the pageInfo object with the library-provided value. The edges property will be transformed to match the Connection schema and any additional properties will be added to the Connection object.

Strategies for determining the hasNextPage value are described in more detail in the library documentation

Try it out

GraphQL pagination can be a complex topic, especially for those new to the Graph data way of thinking. Using this directive allows you to implement powerful pagination functionality without making huge changes to your existing setup.

Hopefully from what you've seen here this library will be able to simplify your GraphQL setup. Full details of configuration options and examples of what can be done with this directive are available in the GitHub repository https://github.com/nearform/relay-pagination-directive