DEV Community: Christine Pinto

Writing Easier Code Comments with ChatGPT

Christine Pinto — Sun, 10 Mar 2024 14:39:20 +0000

In my journey with Playwright, I've discovered how ChatGPT can transform the often tedious task of writing code documentation and comments. This article, part of my series on exploring Playwright, aims to demonstrate just how ChatGPT streamlines this process, making it not only manageable but also efficient. By walking through a Playwright code example, I'll show how leveraging AI can elevate the quality of your code comments, ensuring your work is accessible and understandable to all. Join me as we delve into the benefits of integrating ChatGPT into our coding practices.

The Value of Good Documentation

Good documentation is more than a best practice—it's a cornerstone of effective software development. Statistics from a GitHub survey highlight that 93% of developers consider poorly documented software a significant problem, directly impacting productivity and code quality. Well-documented code, complemented by thorough comments, ensures clarity and accessibility, allowing anyone to understand the work without consulting the original author. This habit not only facilitates smoother transitions and onboarding but also reduces the time spent deciphering code, proving essential in fast-paced development environments where direct communication might not always be possible. Personally, I strongly advocate for enriching code comments with links to resources or code snippets that inspired my solutions, enhancing the educational value of the documentation. This approach not only aids in understanding but also serves as a valuable resource for learning and navigating the codebase more effectively.

Getting Started with ChatGPT for Documentation

To initiate using ChatGPT for generating documentation and comments, consider these prompt types:

Function Explanation Prompt: "Describe the function and usage of this code:" followed by your code. Keywords like "function," "purpose," and "usage" guide ChatGPT to focus on the practical application and significance of the code.
Comment Generation Prompt: "Add comments to this code snippet explaining its logic and any parameters it uses:" followed by the code. Keywords such as "add," "comment," "logic," and "parameters" signal ChatGPT to craft a concise explanation suitable for inline documentation.
Explain Code: "Could you add good comments to explain the code to someone who hasn't built it?" Use keywords like "explain," "comments," and "code" to guide ChatGPT in creating clear, informative annotations for the code, making it understandable for someone unfamiliar with its creation.

Each prompt should be clear and direct, incorporating keywords relevant to the information you seek, such as "explain," "describe," "functionality," and "purpose."

Practical Examples

In the upcoming section, we'll dive into two prompt types using the same code snippets to showcase how ChatGPT can vary its assistance in documenting code and generating comments. This comparative approach will illuminate the versatility and efficiency of AI in enhancing our coding practices, giving us a sneak peek into the evolving world of automated documentation. Full Chat see here.

Original Code Snippet

import { BrowserContext, Page, test as baseTest, chromium } from '@playwright/test';
import path from 'path';
import Landing from '../pages/landing';

export const test = baseTest.extend<{
  context: BrowserContext;
  extensionId: string;
  page: Page;
  landing: Landing;
}>({
  // parts of the setup for the persistent context from https://playwright.dev/docs/chrome-extensions#testing
  context: async ({}, use) => {
    const extPath = path.join(__dirname, '../../build');
    const context = await chromium.launchPersistentContext('', {
      args: [`--disable-extensions-except=${extPath}`, `--load-extension=${extPath}`],
    });
    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
    await use(context);
  },
  extensionId: async ({ context }, use) => {
    let [background] = context.serviceWorkers();
    if (!background) background = await context.waitForEvent('serviceworker');

    const extId = background.url().split('/')[2];
    await use(extId);
  },
  page: async ({ context }, use) => {
    await use(context.pages()[0]);
  },
  landing: async ({ page }, use) => {
    await use(new Landing(page));
  },
});

export const { expect } = baseTest;

First prompt type: Could you add good comments to explain the code to someone who hasn't built it?

// Import necessary modules from Playwright for browser automation and testing, 
// as well as the 'path' module for handling file paths, and the 'Landing' class 
// from a local module, assumed to be a page object model representation of a landing page.
import { BrowserContext, Page, test as baseTest, chromium } from '@playwright/test';
import path from 'path';
import Landing from '../pages/landing';

// Extend the base test context provided by Playwright with additional properties 
// for browser context, extension ID, page, and a specific page object (landing page).
export const test = baseTest.extend<{
  context: BrowserContext;
  extensionId: string;
  page: Page;
  landing: Landing;
}>({
  // Async function to create and configure a browser context for testing a Chrome extension.
  // This setup is part of testing Chrome extensions as per Playwright's documentation.
  context: async ({}, use) => {
    // Resolve the path to the extension's build directory.
    const extPath = path.join(__dirname, '../../build');
    // Launch a persistent browser context with the extension loaded and certain extensions disabled,
    // specifying the path to the extension to load.
    const context = await chromium.launchPersistentContext('', {
      args: [`--disable-extensions-except=${extPath}`, `--load-extension=${extPath}`],
    });
    // Grant permissions necessary for the extension to interact with the clipboard.
    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
    // Use the context in the test.
    await use(context);
  },
  // Async function to extract the extension ID from the service worker associated with the extension.
  // This ID is needed to interact with the extension in the tests.
  extensionId: async ({ context }, use) => {
    // Attempt to retrieve the service worker for the extension.
    let [background] = context.serviceWorkers();
    // If not immediately available, wait for the service worker to become available.
    if (!background) background = await context.waitForEvent('serviceworker');

    // Extract the extension ID from the service worker's URL.
    const extId = background.url().split('/')[2];
    // Use the extension ID in the test.
    await use(extId);
  },
  // Async function to provide the first page in the browser context to the test.
  page: async ({ context }, use) => {
    // Use the first page opened in the context.
    await use(context.pages()[0]);
  },
  // Async function to create and provide an instance of the Landing page object for the test.
  // This allows for easy interaction with the landing page's elements and functionality.
  landing: async ({ page }, use) => {
    // Instantiate the Landing page object with the page provided by the test context.
    await use(new Landing(page));
  },
});

// Export the 'expect' assertion library from baseTest to be used in tests.
// This allows for using expect statements for assertions in the tests.
export const { expect } = baseTest;

Second prompt type: add comments to this code snippet explaining its logic and any parameters it uses

// Import necessary modules from Playwright for browser automation and testing,
// the 'path' module for working with file and directory paths, and a page model for a landing page.
import { BrowserContext, Page, test as baseTest, chromium } from '@playwright/test';
import path from 'path';
import Landing from '../pages/landing';

// Extend the base test with additional configurations specific to the testing needs,
// including a browser context, extension ID, page instance, and an instance of a landing page model.
export const test = baseTest.extend<{
  context: BrowserContext; // The browser context in which the test will run
  extensionId: string; // The ID of the Chrome extension being tested
  page: Page; // A page instance for navigating and interaction
  landing: Landing; // An instance of the landing page model for specific interactions
}>({
  // Configure the browser context for testing Chrome extensions,
  // including setting up the path to the extension and launching a browser instance with it.
  context: async ({}, use) => {
    const extPath = path.join(__dirname, '../../build'); // Determine the path to the extension's build directory
    // Launch a persistent browser context with the extension loaded, disabling other extensions
    const context = await chromium.launchPersistentContext('', {
      args: [`--disable-extensions-except=${extPath}`, `--load-extension=${extPath}`],
    });
    // Grant the browser context permissions to read and write to the clipboard
    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
    // Pass the configured context to the test
    await use(context);
  },
  // Retrieve and provide the extension's ID to the test environment by examining the service worker's URL.
  extensionId: async ({ context }, use) => {
    // Attempt to retrieve the service worker associated with the extension
    let [background] = context.serviceWorkers();
    // If no service worker is immediately available, wait for it to appear
    if (!background) background = await context.waitForEvent('serviceworker');

    // Extract the extension's ID from the service worker's URL
    const extId = background.url().split('/')[2];
    // Provide the extension ID to the test
    await use(extId);
  },
  // Provide the first page opened in the browser context to the test for interaction
  page: async ({ context }, use) => {
    await use(context.pages()[0]);
  },
  // Instantiate and provide the Landing page model to the test, facilitating interaction with the landing page
  landing: async ({ page }, use) => {
    await use(new Landing(page));
  },
});

// Re-export the 'expect' assertion library from baseTest, allowing for assertion use within tests
export const { expect } = baseTest;

Conclusion

In our journey through using ChatGPT for code documentation, we explored its capability to craft detailed comments with two different prompt types. This versatility underscores ChatGPT's adaptability to various documentation needs. A future prospect that holds promise is incorporating the OpenAI API into GitHub actions or commit hooks. This integration could revolutionize the way we ensure our code is consistently well-documented. Nonetheless, the importance of human oversight cannot be overstated. It's crucial to meticulously review AI-generated comments, making necessary adjustments to truly capture the essence of the code, optimizing the blend of AI efficiency with human precision. This balance is key to leveraging AI in enhancing our coding practices, paving the way for a future where code is not just functional but also comprehensively documented and easily understandable.

"Build Your Own Automation Engineer/QA" Sprint Retrospective: A Step-by-Step Guide

Christine Pinto — Mon, 19 Feb 2024 14:31:18 +0000

Intro

Hello, I'm Christine, and I've spent the last 15 years navigating the vibrant and ever-evolving landscape of the tech sector. My journey into the world of Scrum and agile methodologies began over a decade ago, marking a pivotal moment in my career. From that first experience working within a Scrum team, I fell in love with agile software development. It wasn't just the methodologies that captivated me but the philosophy behind agile – the belief in its power to produce outstanding products through collaborative, dynamic team efforts.

Over the years, my passion for agile practices has only deepened. I've immersed myself in multiple courses to broaden my understanding and skills, always eager to bring back valuable insights to my teams. My roles have been diverse, from automation engineering and quality assurance to serving as a Scrum Master on some projects. This unique blend of technical expertise and leadership has given me a comprehensive view of what makes agile teams tick. I found particular joy in facilitating retrospectives and sprint plannings, moments where the team's collective intelligence and creativity come to the forefront to solve problems and improve our processes.

Writing this article stems from a desire to share a piece of that joy and knowledge with others. The "Build Your Own Automation Engineer/QA" Sprint Retrospective is more than just an innovative approach to a meeting; it's a testament to the agile spirit of continuous improvement and team empowerment. Through this guide, I hope to inspire teams to not only embrace automation in their workflows but to do so in a way that fosters creativity, collaboration, and a deeper sense of ownership over their processes. Let's dive into a retrospective theme that promises to unlock new levels of efficiency and innovation within your teams.

Setting the Stage

Objective: Begin by clearly stating the purpose of the retrospective, which is to explore how automation can bolster the team's efficiency and output quality. We gather as a team not just to reflect on past sprints but to envision the future of our testing and development processes. Emphasize the goal of fostering a creative and open environment where innovative ideas can flourish.

Icebreaker: Kick things off with a light, automation-themed icebreaker to help team members relax and get into a creative mindset. This could be a quick round of sharing personal experiences with automation in their daily lives or a fun fact related to technology.

Icebreaker 1: "The Automation Superpower"
Description: Ask each team member to imagine they've just been granted an "automation superpower" that allows them to automate any one task in their daily life, not just work-related. It could be anything from making breakfast to sorting emails. Have each person share what their chosen task would be and why. This not only gets everyone thinking about automation in a fun and personal context but also sparks conversation and laughter about the creative choices and shared human experiences in dealing with mundane tasks.

Icebreaker 2: "Robotic Alias"
Description: Invite each team member to come up with a robotic alias for themselves based on what they would like to automate in their role or what they're known for automating or streamlining within the team. For example, someone who's great at automating test cases might choose the alias "Test-o-Matic." After everyone has shared their alias, have a quick round where each person explains the reason behind their choice. This icebreaker not only sets a fun tone but also highlights each member's contributions to automation in the team.

Gather Data

Current State Analysis: Initiate a group discussion or individual reflection on the current automation practices within your project. What processes are automated? Which ones still rely on manual effort? Utilize a whiteboard, digital document, or sticky notes to create a visual representation of these insights.

Highlight: Ask each team member to identify one manual process in their workflow that they believe could benefit significantly from automation. Encourage them to consider why this process stands out and how automation could resolve existing pain points.

Generate Insights - Build Your Own Automation Engineer/QA Exercise:

Part 1 - Imagine: Invite the team to envision their ideal Automation Engineer or QA bot. What tasks would it take on? How would it interact with the team and existing workflows? Encourage creativity and no-boundaries thinking.
Part 2 - Features and Functions: In smaller groups or as a whole, define the specific features, capabilities, and responsibilities of this imagined Automation Engineer/QA. Consider the different areas it could impact, such as testing, deployment, monitoring, and reporting.
Part 3 - Impact Analysis: Facilitate a discussion on the potential impact of implementing the proposed automation solutions. How would they affect work efficiency, product quality, and team satisfaction?

Decide What to Do

Prioritization: With various ideas on the table, use dot voting or another democratic method to prioritize which automation concepts the team finds most beneficial and feasible.

Action Items: For the top-voted ideas, create detailed action plans including specific tasks, responsible individuals, and deadlines. Make sure there's a realistic approach for exploring or implementing these automation improvements.

Close the Retrospective

Feedback on the Session: Solicit feedback on the retrospective's format and content to gauge its effectiveness and engagement level.

Acknowledgment: Express gratitude for the team's participation and creativity. Highlight the session as a step towards embracing innovation and enhancing team processes.

Tips for Success

Foster Openness: Encourage the team to share freely, ensuring them that every idea, big or small, is valuable.
Make it Enjoyable: Use tools and techniques to keep the session interactive—think digital whiteboards for remote teams or physical sticky notes and markers for in-person gatherings.
Follow Up: Commit to revisiting the action items in subsequent sprints, tracking progress on the implementation of the chosen automation solutions.

By following this guide, you not only conduct a retrospective that's engaging and productive but also position your team to actively contribute to and shape their work environment. The "Build Your Own Automation Engineer/QA" theme not only serves as a catalyst for innovative thinking but also empowers team members to envision and advocate for practical solutions that enhance their daily workflows and project outcomes.

Setup for Testing Chrome Extensions with Playwright

Christine Pinto — Mon, 12 Feb 2024 15:19:57 +0000

Hey everyone! 🚀 If you're diving into the world of Chrome extension testing, you've probably come across a few recommended libraries - Playwright, Selenium, and WebDriverIO. I've had my share of adventures with Selenium, Cypress, TestCafé, and Nightwatch.js, but never penned down my experiences. This time, with Playwright catching my eye (thanks to its growing buzz in the tech community), I thought, "Why not document this journey?"

Why Playwright?

Choosing Playwright felt like stepping into somewhat familiar territory with a twist. It's not just another testing framework; it's designed to handle modern web apps' complexities, offering first-class support for Chrome extensions. The choice was spurred by its promising features and positive mentions in other projects. So, here we are!

The Initial Setup Challenge

Setting up Playwright for Chrome extension testing was a different ball game compared to my routine web app tests. Typically, testing environments are URL-based (local.dev and test.dev!), but extensions require a more nuanced approach. Playwright's setup guide for Chrome extensions is a treasure trove of information, yet the shift in mindset from a URL hosted somewhere on the testing environment or locally to extension-focused testing took a minute to click. It's about making your extension code accessible to Playwright, setting the stage with const pathToExtension to get the ball rolling.

//from the code example on https://playwright.dev/docs/chrome-extensions
import { test as base, chromium, type BrowserContext } from '@playwright/test';
import path from 'path';

export const test = base.extend<{
  context: BrowserContext;
  extensionId: string;
}>({
  context: async ({ }, use) => {
    //path to the chrome extension
    const pathToExtension = path.join(__dirname, 'my-extension');
    const context = await chromium.launchPersistentContext('', {
      headless: false,
      args: [
        `--disable-extensions-except=${pathToExtension}`,
        `--load-extension=${pathToExtension}`,
      ],
    });
    await use(context);
    await context.close();
  },
  extensionId: async ({ context }, use) => {
    /*
    // for manifest v2:
    let [background] = context.backgroundPages()
    if (!background)
      background = await context.waitForEvent('backgroundpage')
    */

    // for manifest v3:
    let [background] = context.serviceWorkers();
    if (!background)
      background = await context.waitForEvent('serviceworker');

    const extensionId = background.url().split('/')[2];
    await use(extensionId);
  },
});
export const expect = test.expect;

Interestingly, I stuck with headless: false, the thought of trying out headless: new is on my radar, promising for future experiments and surely a story to tell.

What's Next?

The plan is to keep this series bite-sized and digestible, aiming for a mix of tutorial, diary, and tech talk. Alongside the practicalities of Playwright, I'll be enlisting ChatGPT's help for language transitioning and solving tricky bugs. Expect to see how this AI tool transforms the way we tackle small coding challenges, especially when it comes to refining TypeScript skills and debugging.

Stay tuned for practical tips, CI/CD development setup, AI-enhanced coding tricks, and more from our Playwright exploration. Let's make this journey together! If you've been tinkering with Playwright or have your own extension testing tales, drop your thoughts below. Sharing is how we grow, and I'm all ears for your experiences and tips.

How to HIGHLIGHT text with Cypress

Christine Pinto — Thu, 22 Jul 2021 03:42:39 +0000

I recently wrote automated UI tests for a text editor application. One of the most important functions was to format text in different ways (e.g. text styles or text alignments). My biggest issue was to figure out how to highlight🖍️ text with Cypress in order to change the formatting of that text.

This feature is an open Github issue in the Cypress repository. I tried out several of their solutions and this is the one which worked best for me:

// Highlight text in the sectionArea
cy.get(sectionArea).realPress(["Shift","ArrowLeft","ArrowLeft"]);

I used the command realPress() from Cypress real events to simulate the highlighting of text via the keyboard⌨️. This was the easiest solution as I have already used other commands from Cypress real events to solve other issues.

UI Test Automation Frameworks Showdown: TestCafé versus Nightwatch.js

Christine Pinto — Mon, 05 Aug 2019 14:45:05 +0000

What is TestCafé?

TestCafé is an end-to-end testing framework, written in JavaScript (JS) or Typescript. It does not leverage Selenium like most other test automation frameworks but instead utilizes a URL-rewriting proxy. TestCafé imitates user activity through the injected driver script by the proxy.

What is Nightwatch.js?

Nightwatch.js is also an end-to-end testing framework based on Node.js that leverages the WebDriver API from Selenium.

Setup

Both frameworks are installed with one npm command:

npm install nightwatch
npm install testcafe

However, after executing this command, only TestCafé is immediately functional. As Nightwatch.js connects to a different browser via the Selenium Server, you will also need to install the Java Development Kit (JDK) — minimum version 7 — in order to enable functionality of this framework.

Mobile Testing

Nightwatch.js is mostly utilized for running on desktop browsers, something that it’s highly noted to do so in other documentation relating to this framework. To leverage the framework for mobile testing, custom configuration of the framework is required alongside Appium, an additional library. The process of enabling this mobile testing can be referenced in this article.

In comparison, due to the usage of the aforementioned proxy instead of the Selenium WebDriver, TestCafé can run on mobile devices by default, without requiring custom configuration.

Writing Code

Using TestCafé requires knowledge of JS, which does not necessarily allow one to quickly switch to or from Selenium WebDriver.

Writing code in Nightwatch.js is uncomplicated and readable. Furthermore, if one uses the frameworks Mocha and Chai, this code will be similar to the JavaScript (JS) unit tests that developers write for JS applications.

Through my years of experience, I have learned and written code in the following test automation frameworks: Geb & Spock (Groovy), Nightwatch.js (Node.js), Menta (PHP), and Selenium (Java). Each of these is written in a different programming language though all use the Selenium WebDriver. Since they are all Selenium based Automation frameworks, the language is very similar to each other because they all use the WebDriver API and this allows you to transition quickly from one framework to another. The setup and configuration of these frameworks vary, most notably in the time required to complete this initial step. Nevertheless, writing the code itself is similar amongst the frameworks as the WebDriver API is used to communicate with the browser.

While this is a clear advantage when considering transitioning to Nightwatch.js, this should not dissuade you from choosing to write code in TestCafé. This is simply to draw attention to the fact that switching to this framework from Selenium is quite different than switching solely between Selenium WebDriver based automation frameworks. In conclusion, though there may be a learning curve required to fully leverage TestCafé’s functionality, there are numerous and valuable onboard features that make writing code more simple and quick.

‘waitFor’ element to appear, element to be visible, or page to ‘load‘

All Selenium WebDriver based automation frameworks require the test to wait for elements to appear or the page to load, which can prove to be challenging in a QA Engineer’s daily work load to write code for automated tests. The automated test is programmed to click on a button and fill out a designated form. This test can only work if you program the automated test to wait until said form is fully loaded, or until the previously clicked button disappears. These ‘waitFor’ functions are found in most of the code and are required to make the automated test stable including, for example, if a connection to a database takes 10ms longer than normal.

TestCafé does not need these specific ‘waitFor’ functions because it automatically waits for page loads or changes. This changes the whole dynamic and structure of building automated tests. The automated test itself is therefore more stable and solid without requiring the addition of the ‘waitFor’ function.

Conclusion

Nightwatch.js is still a superb framework that QA Engineers should use if staying close to the Selenium WebDriver is important. My first article also discussed the benefits present in this framework. After discovering and working with TestCafé, however, I have come to discover that Selenium is not the sole resource available for writing automated UI testing. TestCafé enables a completely new and exciting dimension in UI test automation and should be leveraged by any QA Engineer who is searching for further efficiencies to be gained in the ongoing writing of automated testing.

Originally published at www.pqa.ca

Data-QA Attribute! A better way to select elements for UI test automation

Christine Pinto — Sun, 04 Aug 2019 18:23:30 +0000

I guess everyone who had to automate a web UI had the situation that it was a struggle to find a stable and study selector for some elements on a page. It is important to have stable selectors that the UI automated tests don’t fail if the structure of a page changes or the styling changes.

Why not using ID’s or CSS class names?

ID’s and also css class names have another purpose than for the usage in UI automated tests. CSS classes are primarily used to style elements and they also can get uglified on the production page. ID’s have also another purpose and can also sometimes just change or they are not get implemented because they interfere with other functions on the page.

Solution: Data-qa Attributes

Data-*Attributes are new in HTML 5. These HTML attributes enable us to create custom attributes on every HTML element. So the solution is to create ‘data-QA’ attributes for HTML elements. These attributes can be only used for the UI automated test and don’t interfere with any functions or purposes on the page.

DEV Community: Christine Pinto

Writing Easier Code Comments with ChatGPT

The Value of Good Documentation

Getting Started with ChatGPT for Documentation

Practical Examples

Conclusion

"Build Your Own Automation Engineer/QA" Sprint Retrospective: A Step-by-Step Guide

Intro

Setting the Stage

Gather Data

Generate Insights - Build Your Own Automation Engineer/QA Exercise:

Decide What to Do

Close the Retrospective

Tips for Success

Setup for Testing Chrome Extensions with Playwright

Why Playwright?

The Initial Setup Challenge

What's Next?

How to HIGHLIGHT text with Cypress

UI Test Automation Frameworks Showdown: TestCafé versus Nightwatch.js

What is TestCafé?

What is Nightwatch.js?

Setup

Mobile Testing

Writing Code

‘waitFor’ element to appear, element to be visible, or page to ‘load‘

Conclusion

Data-QA Attribute! A better way to select elements for UI test automation

Why not using ID’s or CSS class names?

Solution: Data-qa Attributes

Examples for data-qa attributes