Forem: Ifeoma Imoh

Remove Image Background With Cloudinary and Pixelz: A Tutorial

Ifeoma Imoh — Wed, 06 Apr 2022 10:57:08 +0000

For all that images are an essential communication medium, their background is just as important because a noisy background tends to draw attention away from images. To resolve that issue, replace the original background with an artificial one for various contexts, such as colored T-shirts, webpage headers, etc.

This tutorial describes how to remove the background of an image with Cloudinary and Pixelz. You start with building a React app that uploads an image and then proceeds to remove its background. Afterwards, hook into the process and build a mechanism that notifies you by email when the removal process is complete.

Keep in mind the following:

You must be on a paid Cloudinary plan to access the features required, which are a premium Cloudinary offering. You must also subscribe to Cloudinary’s Pixelz add-on.
Background removal is carried out asynchronously by a team of human experts, who could take up to 24 hours to complete the task.

A demo is on CodeSandbox.

Setting Up the Project

First, set up the project:

Create a React app with this command:

    npx create-react-app image_background_remover

Add the project dependencies:

    npm install antd @ant-design/icons axios

Import the CSS for antd by adding ~antd/dist/antd.css to the App.css file in your src directory:

    @import "~antd/dist/antd.css";

Setting Up Cloudinary

First, sign up for a free Cloudinary account. Displayed on your account’s Management Console (aka Dashboard) are important details: your cloud name, API key, etc.

Since you’ll be sending images to Cloudinary through unsigned POST requests, create an unsigned upload preset, as follows:

On the Management Console, choose Settings > Upload for the page with upload settings.
Scroll to the Upload presets section and click Add upload preset at the bottom of the section.
On the page that’s displayed, choose Unsigned from the pull-down menu under Signing Mode.
Click Media analysis and AI in the left-navigation area and, on the page that’s displayed, choose Pixelz from the pull-down menu under Background removal. Click Save at the top.
Copy the name of the upload preset you just created for later use.

Next, create environment variables to hold the details of your Cloudinary account. Follow these steps:

Create a file called .env at the root of the project with the content below. Be sure to replace the two variables after the = symbol with their values.

    REACT_APP_CLOUD_NAME = Your cloud name
    REACT_APP_UPLOAD_PRESET = Your unsigned upload-preset key

These two settings will serve as the default if you set up the project on another system. To update your local environment, create a copy of the .env file by running this command:

    cp .env .env.local

By default, this local file resides in the .gitignore folder, mitigating the security risk of inadvertently exposing secret credentials to the public. You can update the .env.local file with your Cloudinary account’s cloud name and the upload preset you created earlier.

In the root directory of your project, create a folder named utility for the helper classes for your components.
In your src folder, create a file named cloudinaryConfig.js for accessing the environment variables and for preventing repeated process.env. calls throughout the project.
Add the code below to the cloudinaryConfig.js file. Be sure to replace the two variables, React_app_cloud_name and React_app_upload_preset, with their values.

    export const cloudName = process.env.React_app_cloud_name;
    export const uploadPreset = process.env.React_app_upload_preset;

Creating a Helper Class for API Requests

Now write a helper function for uploading an image to Cloudinary before starting the background-removal process. In the utility folder, create a file named api.js with this code:

    import axios from 'axios';
    import { cloudName, uploadPreset } from './cloudinaryConfig';
    export const uploadImage = ({ file, successCallback }) => {
      const url = `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`;
      const data = new FormData();
      data.append('file', file);
      data.append('upload_preset', uploadPreset);
      axios
        .post(url, data, {
          headers: {
            'Content-Type': 'multipart/form-data',
          },
        })
        .then((response) => successCallback(response.data));
    };

The uploadImage function uploads the file as specified to Cloudinary by making a POST request to Cloudinary along with the file name and the name of the upload preset you created earlier. On successful completion of the request, uploadImage executes the callback, passing the Cloudinary response as a function parameter.

Creating the Components

Next, create the components:

In your project's src folder, create a folder called components.
In the src/components folder, create a file called ImageSelector.js with this code:

    import { Button, Upload } from 'antd';
    import { UploadOutlined } from '@ant-design/icons';
    const ImageSelector = ({ setImage }) => {
      const props = {
        name: 'file',
        onRemove: () => {
          setImage(null);
        },
        beforeUpload: (selectedImage) => {
          setImage(selectedImage);
          return false;
        },
        showUploadList: false,
        maxCount: 1,
      };
      return (
        <Upload {...props}>
          <Button icon={<UploadOutlined />}>Select Image</Button>
        </Upload>
      );
    };
    export default ImageSelector;

By way of explanation:

The ImageSelector component takes setImage, a callback function that updates the app state with the latest image you uploaded.
By returning false in the beforeUpload key of props, you’ve disabled the default behavior of the [Upload](https://ant.design/components/upload/) component, which uploads the selected file to the URL as specified. You’ve also restricted the maximum number of files to 1.

Putting It All Together

Replace the content of your src/App.js file with the following code:

    import './App.css';
    import { Button, Card, Col, Form, Input, message } from 'antd';
    import { useState } from 'react';
    import ImageSelector from './components/ImageSelector';
    import { uploadImage } from './util/api';
    function App() {
      const [image, setImage] = useState(null);
      const [isUploading, setIsUploading] = useState(false);
      const formItemLayout = {
        labelCol: {
          sm: { span: 4 },
        },
        wrapperCol: {
          sm: { span: 18 },
        },
      };
      const onFailedSubmission = (errorInfo) => {
        console.log('Failed:', errorInfo);
      };
      const onFinish = (values) => {
        if (image === null) {
          message.error('You need to upload an image first');
        } else {
          setIsUploading(true);
          uploadImage({
            file: image,
            successCallback: (data) => {
              setIsUploading(false);
              console.log(data);
              message.success('Image uploaded successfully.');
            },
          });
        }
      };
      return (
        <div style={{ margin: '1%' }}>
          <Card style={{ margin: 'auto', width: '50%' }}>
            <Form
              {...formItemLayout}
              onFinish={onFinish}
              onFinishFailed={onFailedSubmission}
              autoComplete="off"
            >
              <Col span={8} offset={9} style={{ marginBottom: '10px' }}>
                <ImageSelector setImage={setImage} />
              </Col>
              <Form.Item wrapperCol={{ offset: 10, span: 16 }}>
                <Button type="primary" htmlType="submit" loading={isUploading}>
                  Submit
                </Button>
              </Form.Item>
            </Form>
          </Card>
        </div>
      );
    }
    export default App;

By way of explanation:

You’ve declared two state variables: one for the uploaded image and the other as a depiction of whether the image is being uploaded.
The formItemLayout is an object that contains the size specifications for the label columns in the form to be created. Failure to validate the submitted form triggers the onFailedSubmission function.
You’ve logged errors to Cloudinary’s Management Console, which displays a warning message if errors are present.
If the data in the submitted form is valid, the onFinish function is called. Absent a selection of an image, onFinish displays an error message. Otherwise, the uploadImage function declared in api.js uploads the image to Cloudinary .
On a successful upload, uploadImage displays a message to that effect in Cloudinary’s Management Console .
You’ve rendered the ImageSelector component so that you can select an image for upload. On such a selection and a click of the Submit button, the onFinish function uploads the image to Cloudinary.

Now run the app with this command:

    npm start

By default, the app is at http://localhost:3000/. Upon successful selection and upload of an image, this response is displayed in the Management Console:

    "url":"http://res.cloudinary.com/<cloud_name>/image/upload/v1647108022/<public_id>.jpg",
    "secure_url":"https://res.cloudinary.com/<cloud_name>/image/upload/v1647108022/<public_id>.jpg",
    "info":{
          "background_removal":{
             "remove_the_background":{
                "status":"pending"
             }
          }
       },

As mentioned earlier, the background-removal process is asynchronous. Once it’s complete, the edited version replaces the original image and is accessible through Cloudinary’s Management console or content delivery network (CDN).

Adding Status Notifications

To keep checking the URL in the response for the updated image is an unproductive use of time. Instead, leverage the Cloudinary feature that notifies you by email when an editing process is a wrap. To that end, build an API that handles notifications from Cloudinary and that emails you the edited version of the uploaded image.

First, create a project folder named cloudinaryNotificationHandler for these two API files:

server.js, which handles the incoming requests and sends the appropriate response.
helper.js, which performs such tasks as downloading images and sending emails.

Setting Up the Mailing Process

Perform these steps to establish the email-notification process:

Install and add Nodemailer to your project:

    npm install nodemailer

Note: Feel free to use another Simple Mail Transfer Protocol (SMTP) mail provider of your choice.

Set up Mailtrap by creating a Mailtrap account. If you already have one, log in.
Click the Show Credentials link in the SMTP Settings tab, copy your user name and password, and save them for a later step.

Setting Up the Helper Functions

Add the following to your helper.js file:

    const fs = require('fs');
    const client = require('https');
    const nodemailer = require('nodemailer');
    const buildCloudinaryUrl = (version, publicId) => {
      const cloudName = 'INSERT YOUR CLOUD NAME HERE';
      return `https://res.cloudinary.com/${cloudName}/image/upload/v${version}/${publicId}.jpg`;
    };
    const downloadImage = (url, filepath) =>
      new Promise((resolve, reject) => {
        client.get(url, (res) => {
          if (res.statusCode === 200) {
            res
              .pipe(fs.createWriteStream(filepath))
              .on('error', reject)
              .once('close', () => resolve(filepath));
          } else {
            res.resume();
            reject(
              new Error(`Request Failed With a Status Code: ${res.statusCode}`)
            );
          }
        });
      });
    const sendMail = (content, filepath) =>
      new Promise((resolve, reject) => {
        const transport = nodemailer.createTransport({
          host: 'smtp.mailtrap.io',
          port: 2525,
          auth: {
            user: 'INSERT YOUR MAILTRAP USER name HERE',
            pass: 'INSERT YOUR MAILTRAP PASSWORD HERE',
          },
        });
        const message = {
          from: 'from-example@email.com',
          to: 'to-example@email.com',
          subject: 'Image Background Removal Complete',
          html: `
          <p> Hi there!!!</p>
          <p>The image processing is complete, here are the notification details </p>
          <code>${JSON.stringify(content)}</code>
          `,
          attachments: [{ filename: filepath, path: filepath }],
        };
        transport.sendMail(message, (error, info) => {
          if (error) {
            reject(error);
          }
        });
      });
    module.exports = { downloadImage, sendMail, buildCloudinaryUrl };

By way of explanation:

Based on two parameters—the image URL and the file path in which to save the image—the downloadImage function makes a GET request to the URL and writes the content of the response to that path.
Also based on two parameters—content, the information sent by Cloudinary; and filepath, the path in which the edited image resides—the sendMail function sets up a Nodemailer transport and sends an email with the edited image as an attachment.

Add the following to your server.js file:

    const http = require('http');
    const { downloadImage, sendMail, buildCloudinaryUrl } = require('./helper');
    const host = 'localhost';
    const port = 8000;
    const requestListener = async (req, res) => {
      const buffers = [];
      console.log(123);
      for await (const chunk of req) {
        buffers.push(chunk);
      }
      const data = Buffer.concat(buffers).toString();
      const parsedData = JSON.parse(data);
      const { public_id, version, secure_url } = parsedData;
      const filepath = `${public_id}.jpg`;
      fileUrl = buildCloudinaryUrl(version, public_id);
      console.log(fileUrl);
      await downloadImage(fileUrl, filepath);
      sendMail(parsedData, filepath);
      res.setHeader('Content-Type', 'application/json');
      res.writeHead(204);
      res.end(null);
    };
    const server = http.createServer(requestListener);
    server.listen(port, host, () => {
      console.log(`Server is running on http://${host}:${port}`);
    });

Here:

You’ve declared a request listener for handling requests, i.e., extract their content and then retrieve the public ID and version specified there. The buildCloudinaryUrl function builds the URL for the edited image so that it’s in JPEG format with a .jpg file extension.
The downloadImage function downloads the image; the sendMail helper function sends the image by email. Finally, a 204 response is returned, informing you that the response contains no content.

Now serve the app by running this command:

    node server.js

Next, test the setup by sending the sample POST request generated by Cloudinary for your API.

    {
      "notification_type": "info",
      "info_kind": "pixelz",
      "info_status": "complete",
      "public_id": "wood_chair",
      "uploaded_at": "2014-10-26T11:35:22Z",
      "version": 1414316122,
      "url": 
        "https://res.cloudinary.com/demo/image/upload/v1393688588/wood_chair.jpg",
      "secure_url":
        "https://res.cloudinary.com/demo/image/upload/v1393688588/wood_chair.jpg",
      "etag": "a56e9e88c2add15cac1775c1f687bf73"
    }

Everything looks good, except that your setup is local. The next section describes how to expose that local setup to Cloudinary.

Specifying the Port Number Through Ngrok

To expose your app, which is running, to the internet, leverage the cross-platform app Ngrok. Follow these steps:

Download the Ngrok executable file and unzip it.
Run the Ngrok http command to specify the port number you’d like to be exposed. Since your API runs on port 8000, type:

    ngrok http 8000

Afterwards, start Ngrok, which will display in your terminal the public URL of your tunnel and the status and metrics that pertain to the connections made over your tunnel. See this example:

Specifying the Notification URL

Now that you’ve built the tunnel and your app is running, configure your upload preset in Cloudinary so that the preset will let you know when the image-removal process is complete. Here’s what to do:

On the Management Console, choose Settings > Upload and scroll to the Upload presets section.
Click Edit next to the upload preset you created earlier and then click Upload Manipulations in the left-navigation area.
In the Notification URL text field, paste the URL displayed on the Ngrok terminal and click Save at the top.

Here’s the complete code of this project on GitHub.

Summing Up

This tutorial walks you through the procedures for the following:

Remove the background of an image with Cloudinary and Pixelz.
Build a simple Node HTTP server to handle POST requests and send notifications by email—no need to refresh pages or worry about when background removal will be complete. Pretty neat, right?
Link a localhost app to your Cloudinary account’s Management Console with Ngrok.

For further reference, see the documentation on Cloudinary’s Pixelz add-on, Mailtrap, and Ngrok.

Understand JavaScript Abstract Operations in 7 Minutes.

Ifeoma Imoh — Mon, 01 Feb 2021 12:19:09 +0000

To help you understand better, let’s quickly revisit types in JavaScript. Variables in JavaScript do not have types; values do. JavaScript has eight basic value data types, and they are divided into two categories, primitive and non-primitive.

Primitive Types:

Undefined
Null
Boolean
String
Symbol
Number
BigInt

Non-Primitive Types (Reference types):

Object
Array
Function

Arrays and functions are subtypes of the object type.

One major difference between primitive and non-primitive values is that primitive values are immutable after creation while non-primitive values are mutable.

Let’s take an example:

// Let's alter the value of the string assigned to the variable person.
let person = "ifeoma"
// Here it simply made a copy and then altered the copied value.
console.log(person.toUpperCase()) // IFEOMA
// It didn't change the original value.
console.log(person) //  ifeoma

From the example above, when we tried to alter the value, it only made a copy of the variable person and changed it, but it didn’t change the already existing string value because it is a primitive.

On the other hand, the variable assigned to a primitive value can be changed. Therefore, it can be reassigned so that it points to a new value but the existing value it holds cannot be changed.

let person = "ifeoma"
person = "sylvia"
console.log(person)  // sylvia

In the example above, we assigned a new string value to the variable person so that it no longer points to the initial string value ifeoma .

Let’s try to mutate a non-primitive:

let array = [ "Jay Pritchet", "Phil Dunphy" ]
let array2 = array
array.push("Claire Pritchet")
console.log(array2) // [ "Jay Pritchet", "Phil Dunphy", "Claire Pritchet" ]

In the above example, we made array a reference to array2 . Emphasis on reference, which means that even after we modified the data in array by adding a new item to it, logging array2 shows the new item added to array .
This is because the variable array2 is referencing the address of the variable array.
This behavior is expected from all non-primitive value types.

Another difference between primitives and non-primitives is that primitives are stored by value while non-primitives are stored by reference.

The typeOf operator is a built-in utility used to check the type of value assigned to a javascript variable.

The typeOf operator always returns a string type.

Let’s take a look at how values are changed from one type to another.

Coercion

Coercion refers to the process of converting values from one type to another(such as string to number ).
Using inbuilt functions(Number(), String() etc.) you can be obvious about your intention to convert a value from one type to another(explicit coercion) or let Javascript automatically handle the conversion for you(Implicit coercion).

Coercion always results in either strings , numbers , or booleans . Understanding coercion will help you avoid problems that can occur in your code.
Let's see some examples.

Implicit Coercion

5 - "1" // 4  JavaScript coerced the string 1 to a number.
10 * false // 0  Javascript coerced the boolean false to 0.
10 + true // 11  The boolean true is coerced to a number 1.

Explicit Coercion

Number('5') - Number('2') // 3 Here we are explicitly converting both strings to numbers first using the Number() method.

To fully understand how coercion happens, we need to talk about Abstract Operations.

Abstract Operations are the fundamental building block that makes up how we deal with type conversion. - Kyle Simpson

Abstract Operations

According to the ECMAScript specification, abstract operations are not part of the language specification, but they are responsible for performing type conversion in Javascript. Whenever coercion (implicit or explicit) occurs, one or more internal operations, known as abstract operations, are performed.

We will look at these four primary abstract operations, but you can find the rest of them in the spec.

ToPrimitive()
ToString()
ToNumber()
ToBoolean()

ToPrimitive()

When a non-primitive or reference value is used in the context where a primitive is required, the JavaScript engine calls the ToPrimitive() abstract operation.

When converting non-primitive types to primitives, the abstract operation ToPrimitive() is invoked to handle the operation.

Let's see how non-primitive values are converted to primitives.

The spec informs us that the ToPrimitive() abstract operation takes two arguments.

An input
An optional PreferredType hint

The PreferredType hint can be either one of these - string , number , default .

If you are performing a numeric operation and the ToPrimitive() operation is invoked, number will be sent as the hint. If you are working with strings, it will send string as the hint.
When ToPrimitive() is called with no hint present, it'll send default as a hint, and this will behave as if the hint were number (unless it's a Date which defaults to string ).

If the argument is already a primitive value, then it will be returned without conversion. Let's take a look at how the ToPrimitive algorithm works.

There are two methods available on every object type used to convert them from non-primitives to primitives:

valueOf() — This is to retrieve the primitive value associated with an object.
toString()

Number Algorithm
If the hint is number , it calls the valueOf() function first, and if the returned value is primitive, it'll use it. If the object has no primitive value, valueOf() returns the object back then the toString() function gets called. Its value will be used if it is primitive; otherwise, it would result in a type error.

String Algorithm
If the hint is string , the order is reversed compared to the number algorithm. It calls the non-primitive toString() function first, and if it gets a string representation, it'll just use it; otherwise, it'll try the valueOf() method to see if the object has any primitive value.

Default Algorithm
If no hint is sent, it sets the default hint to number , or it is set to string if it is a Date .

The algorithms within JavaScript are inherently recursive. This means that if the ToPrimitive() operation gets invoked and the return result is not a primitive, it will keep getting invoked until it returns a primitive or an error.

ToString()

This abstract operation takes any value and converts it to a representation of the value in string form.

Argument	Result
Null	“null”
Undefined	“undefined
true	“true”
false	“false”
“Hi”	“Hi”
Symbol	Throw a TypeError exception.

As seen above, built-in primitives have natural stringification, but if the ToString() operation is called on an object type, it will invoke the ToPrimitive() operation, and pass string as the hint.

As explained earlier, this will call the toString() first, and if it gets a string representation, it'll just use it; otherwise, it'll try the valueOf() method.

By default, regular JavaScript objects have their built-in toString() method (located in Object.prototype.toString()) that is called when an object is used in a manner in which a string is expected and this will return their internal [[Class]] property (e.g [object Object]).

Unless you specify your toString() method, if you use an object in a string-like way, the toString() method on its object prototype will be called. This will return a string with the [object Type] format where Type is the object type.

Let’s see an example:

const obj = {}
obj.toString() // [object Object]

Although arrays are subtypes of the object type, the array object has a built-in toString() method that overrides the default Object.toString() method and returns a string representation containing each array element separated by a comma. This toString() method lives on the Array’s prototype as Array.prototype.toString().

Here is an example:

// Calling toString() explicitly on an array
let array = []
array.toString() // ""  It returns an empty string.

let array1 = [1, 2, 3]
array1.toString() // "1,2,3"  It returns a string containing each element in the array seperated by a comma.

In a situation where you want to get the object class, you need to skip the default override behavior of Array.prototype.toString in favor of Object.prototype.toString() .

You have to pass the array in the call() method to change the context from Array to Object.

console.log(Object.prototype.toString.call([1, 2, 3])) // [object Array]

ToNumber()

Whenever we perform a numeric operation, and one or both operands aren't numbers, the ToNumber() abstract operation will be invoked to convert it to a value of type number .
Let's see some examples:

Argument	Result
undefined	NaN
null	0
true	1
false	0
“”	0
“.”	NaN
“1”	1
BigInt	Throw a type error exception.
symbol	Throw a type error exception.
object	1. ToPrimitive(argument, number). 2. Return ? ToNumber(primValue).

As seen from the table above, when ToNumber() is called on a non-primitive (any of the object types) value, it is first converted to its primitive equivalent by invoking ToPrimitive() abstract operation and passing number as the PreferredType hint.
The return value from the ToPrimitive() operation will then be coerced into a number by the ToNumber() abstract operation. If it still doesn't result in a primitive value, it throws an error.

Let's take an array with an empty string as an example.

ToPrimitive( [""], number) // It first calls the ToPrimitive abstract operation on it and pass number as the hint.

[""].valueOf() // [""]  Because  the hint is number, it calls valueOf first and this basically returns itself. So we still have the array with an empty string which isn’t a primitive.

[""].toString() // ""   It then calls the toString() function next and this will end up producing an empty string "".

ToNumber("") // 0   Next it calls ToNumber() and passes the empty string "" as an argument. As seen from the table above, that would result to 0.

ToBoolean()

The abstract operation ToBoolean() is called to convert an argument to a Boolean type whenever we use a value that is not Boolean in a place that needs a Boolean . The ToBoolean() abstract operation does not invoke the ToPrimitive() or any of the other abstract operations.
It just checks to see if the value is either falsy or not. There is a lookup table in the spec that defines a list of values that will return false when coerced to a boolean . They are called falsy values.

These are the falsy values:

Argument Type	Result
undefined	false
null	false
false	false
NaN	false
0	false
-0	false
“”	false

Values that are not on the list of falsy values are truthy values.

Conclusion

Languages that take the first position about their rules are referred to as "strongly typed" because they are strict about not allowing you to break the rules.
Since JavaScript is not one of them, it is referred to as weakly or loosely typed because it gives room for a lot of flexibility in terms of implicit coercion, and you do not have to specify the type of your variables explicitly.

Like any other language, Javascript has its rules, and the rules that govern the type system of a language exist to help us. It is up to us to learn them to avoid unnecessary mistakes.

Thank you! I hope you enjoyed reading as much as I enjoyed writing ❤️.

A Complete Git and GitHub Workflow Using VS Code Only

Ifeoma Imoh — Wed, 02 Dec 2020 11:07:24 +0000

I recently discovered that I could integrate Github into my Visual Studio Code. This means that I can create pull requests, create issues, clone repositories, collaborate with others, etc., without leaving VS Code. I was excited and decided to write about it. In this article, we’ll go over how to complete some of the things we do on Github right in VS Code.

We will cover the following:

Setup
Clone a project
Stage and commit
Create a new branch
Stash changes
Push changes
View commit timeline
Create pull requests
Pull from a remote repository
Add a remote repository
Publish a new project

Prerequisites

I’m assuming you have some experience with Git, GitHub, and VSCode. You can still follow along if you do not have any experience, but you’ll need the following:

A GitHub account.
Visual Studio Code installed in your machine.
Git installed in your machine.

VS Code has a Git integration as one of its source control options, but for it to work, Git needs to be installed on your machine.

Setup

Integrating Github with VS Code is done through Github Pull Requests and Issues extension.
Open VS Code and click on the extensions panel. Search for GitHub Pull Requests and Issues. Next, install the extension and authenticate with GitHub.

After installing the extension, click on the account icon on the activity bar to log in to your GitHub account.

Click on the “Sign in to use GitHub Pull Request and Issues link.

VS Code will navigate you to the browser. Click on the Continue button to give VS Code access to GitHub.

You will see a screen asking if you want to authorize GitHub for VS Code. Click the Authorize GitHub button.

Confirm your GitHub password to continue. You will see a success screen with your authorization token as displayed below.

If you are not redirected to VS Code, copy the token manually and switch back to VS Code. Click on “Signing in to github.com” in the Git status bar at the bottom of the screen, paste the token and press the Enter or return key on your keyboard. You may need to reload your VS Code window for the extension to start working.

Clone a project

We will clone by clicking on the Clone Repository button in the source control view. Click on the “Clone from GitHub” link as seen below.

You will see a dropdown asking if you want to enable authentication through GitHub. Click the Allow button. VS Code may redirect you to your browser, where you need to authorize GitHub for VS Code like we did when setting up; otherwise, you should see a dropdown with a list of the repositories you have on your GitHub account. You can search for and clone any repository on GitHub.

Select where you want the repository to be stored. If you already have a folder, select it and click the Select Repository Location button. You can also open your desired folder on VS Code and then clone into it.

Once it finishes, you will see a prompt on VS Code asking if you want to open your cloned file in the current window or a new window.

If you want to clone a repository belonging to someone else, you can click on the Clone Repository button in the source control view. Paste the URL of the repository in the search bar.

See the example below.

Stage and commit

While working or making changes to files, your source control tab should reflect the number of files you have made changes.
Click on the source control tab to see a list of all the files you’ve made changes to. Click on any file or hover over it until you see a plus sign appear. Click on the plus sign, and VS Code will add the file to your staging environment.

If you have many files and want to stage all of them, instead of clicking the plus sign one after the other, you can click on the More Actions menu (...). From the dropdown, select Changes and select Stage All Changes.

To commit the staged files, add your commit message and click the checkmark. This will save your changes to your local repository.

Create a new branch

Click the current branch name from the git status bar.
Select “Create new branch” from the dropdown - this will create a branch from the current branch you are working on.
Type in the name of the new branch and hit Enter. VS Code will automatically switch to the new branch.

Create a branch from an already existing branch

From the dropdown, select “Create new branch from…” - This will create a new branch from some other branch in the current git repository.

Stash Changes

If you are working on something and do not want to commit the changes yet, probably because you haven’t finished working on them, you need to stash them. Stashing them will move your modified files into a stack of unfinished changes and leave you with a clean working directory. You can restore the stashed files at any time, even on a different branch.

Click on the source control tab.
Click on the More Actions menu (...) on the changes view.

Select Stash from the dropdown.
Select Stash again.

VS Code will prompt you to enter a stash message to identify the stash and hit the Enter key. You will have a clean working directory now.

To restore stashed changes, click on the More Actions menu (...), hover over Stash and select Apply Stash.

You will see a dropdown of your stashed changes. In the screenshot above, we have just one. Go ahead and select the stash you want to apply. This will apply the changes and still leave the entry in the stash.
If you want to restore the stashed changes and delete the entry from the list of stashes, instead of selecting Apply Stash, select Pop Stash from the dropdown.

Push changes

To push changes in your local repository to a remote repository on GitHub that you own or are a contributor to:

Click on the source control tab
Click on the More Actions menu (...)
From the dropdown, select Push, Pull.
From the dropdown, select Push to…

You will be given an option of any configured remote repository.

Select the repository, and that’s it. If you want to check if the changes were pushed to GitHub, you can go to the GitHub repository and confirm.

View commit timeline

You can view the Git commit history of every file in the timeline view. The timeline view will, by default, update to show the timeline for whatever file you currently have open.

To view the timeline for a specific file in your project:

Click on the file.
Scroll down to the bottom of the File Explorer and click on Timeline.

For every commit in the Timeline, you’ll see the commit title, the name of the person who made the commit, and when that commit was made.
If you click on any commit, it’ll show you a diff view of the changes made by that commit.

Create pull requests

To create a pull request after the changes in the local repository has been pushed to the remote repository on GitHub, you’ll need to do the following:

Click on the GitHub Pull Request tab to open the Pull Requests view.
Click on the + button.
Choose the target branch for the pull request and hit the Enter key.

If your branch hasn’t been published yet, the extension will do it for you. After completing the first three steps above, VS Code will prompt you to pick a name for the branch and hit the Enter key.

After publishing the branch, you’ll need to select a title for the pull request. From the menu, as seen in the screenshot below, you can use the latest commit message, the branch name, or specify a custom title.

Once you select the pull request title, your pull request will be created.
You can add a code reviewer and label if you want.

Pull from a remote repository

To pull from a remote branch into your local repository, you need to do the following:

Click on the source control tab.
Click on the More Actions menu (...).
From the dropdown, select Pull, Push.
From the dropdown, select Pull if you have **only one remote connected or **Pull from if you have multiple remotes to pick from.

If you select Pull from, you’ll need to select the remote you want to pull from. As seen below, I have only my default remote, which is origin.

You’ll also need to select a branch to pull from.

Once you select your branch, that’s it!!

Add a remote repository

To add a remote repository to your project:

Click on the source control menu.
Click on the More Actions menu (...).
From the dropdown, select Remote and click on Add Remote…

You can either provide the repository URL or add a remote from GitHub.
Click on Add remote from GitHub. You can search for a repository name or select one from the dropdown as seen below.

Next, you’ll have to provide a remote name you can reference easily and press Enter.

To add remote from URL, you can paste the repository URL in the search bar and follow the same steps.

Publish a new project

Open your project on VS Code.
Click on the source control menu.
Click on Publish to GitHub button - This option is only available if git has not been initialized in the project.
You’ll have to decide if you want to make it a public or private repository
Select the file you want to include in the first commit and click the Ok button.

I created just the index.html file for this illustration, as seen below.

The repository has been successfully published to Github.

Yayyy!! You made it to the end of this post, and I hope that you found new tips or tricks to enhance your productivity regardless of your experience level. I bet you’d agree with me that this is the coolest thing since Jollof rice. If you haven’t had Jollof rice, we need to fix that!! Thank you for reading!

Continuous Integration for End-To-End Tests with Cypress and GitHub Actions

Ifeoma Imoh — Tue, 10 Nov 2020 08:32:16 +0000

In this article, we are going to learn how to create a continuous integration process for Cypress tests. Github Actions can automate, customize and execute your software development workflows right in your repository and it also supports software project development in a variety of ways, both in Programming Language and Operating System Stack.

Continuous Integration (CI), is a software development practice which requires automating the integration of software changes from multiple contributors into a single software project. Each change is validated by creating a build and running automated tests against the build. Getting fast feedback on the impact and outcome of changes lead to better collaboration and software quality.

This article will cover the following:

How to create your first GitHub Actions to run Cypress tests on a hosted website.
Schedule GitHub Actions Jobs to run at a given interval.
How to setup GitHub Actions to run Cypress tests for a local project.
Send test results to Cypress dashboard for monitoring.

Cypress team has open sourced an action to make running Cypress end-to-end on GitHub easy. Let’s get started.

Prerequisites

The only required prerequisites is that you should have some experience writing Cypress tests. No prior GitHub Actions experience is required.

Setting up GitHub Actions to Run Cypress Tests on a Hosted Website

A workflow is a configurable automated process made up of one or multiple Jobs (Jobs will be explained further down this post). Workflow files must be stored in .github/workflow directory of your repository and they are defined using YAML syntax (.yml or .yaml file extension). If you are new to YAML and want to learn more, I would recommend this Learn YMAL in five minutes.

Cypress doesn’t recommend running tests on a deployed website Instead, tests should be part of your code project and should live in the same repository. This way it is more efficient to manage and ship code using CI.

First, you need to create a .github/workflows folder with a main.yml file in the project directory and add these code snippets into the main.yml file.

name: This is the name of our workflow. GitHub is going to display this on our repository’s action page.

    name: E2E tests

on: This is the event that triggers the workflow. This can be a single event, an array of events or an event configuration map that schedules. In our case here, this triggers the workflow on push or pull request but only for the develop branch. We are also specifying an array of different activity types for our pull request event.

    on:
      push:
        branches:
          - develop
      pull_request:
        types: [opened, synchronize, reopened]
        branches:
          - develop

jobs: We now know that a workflow can be made up of one job or a collection of jobs. Jobs run at the same time in parallel (default) or sequentially depending on the status of a previous job. Jobs run in their own environments specified by runs-on and here we are using the latest version of ubuntu. For each job, a virtual machine is spawned and other jobs won’t be able to access it.

    jobs:
      cypress-run:
        runs-on: ubuntu-latest
        timeout-minutes: 10

steps: A job is made up of small sub-tasks called steps. In each step, we can run commands, run setup tasks or run an action in our public repository. Not all steps run an action but all actions run as a step. As seen below, we have three steps:

    steps:
        - name: Checkout
          uses: actions/checkout@v1
        - name: Setup npm package
          run: npm install
        - name: Run E2E test
          uses: cypress-io/github-action@v1
          with:
            config: baseUrl=https://seedxb.com

The name field is what GitHub displays as the name of the step inside the actions tab.
The checkout action is is going to clone the repository inside the workspace directory in GitHub action environment.
The Setup npm package as the name implies will run npm install on the cloned repository and install all our dependencies and The run field specifies a Bash command to run for this step.

The last step, Run E2E test will use Cypress GitHub actions to run our tests for us. We do not need to explicitly specify the run command for the test.

With This field specifies options to configure the action. Actions are like functions and they can define parameters to influence their behaviours dynamically. Here, our action parameter is defined using with which is a key/value map. In our case, we are passing a config parameter using with .

we can use public actions such as actions/checkout@v1 or run command line programs, as we do here with npm install.

Now you can push to your repository and you’ll see a new tab under the repository called Actions, click it.

Schedule GH Actions Jobs to run at a given interval

We can also setup our workflow to run on a schedule using POSIX cron syntax independent of any activity on the repository. The schedule event lets us define a schedule for our workflow to run on. As seen below, the scheduled event here gets triggered at 9am daily. GitHub provides detailed documentation on scheduled events here.

    on:
      # push
      # pull_request
      schedule:
        - cron: '0 9 * * *'

Now this is what our code should look like: -

    name: E2E tests
    on:
      push:
        branches:
          - develop
      pull_request:
        types: [opened, synchronize, reopened]
        branches:
          - develop
       schedule:
         - cron: "*/5 * * * *"
    jobs:
      cypress-run:
        timeout-minutes: 10
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v1
          - name: Setup npm package
            run: npm install
          - name: Run E2E test
            uses: cypress-io/github-action@v1
            with:
              config: baseUrl=https://seedxb.com

How to Setup GitHub Actions to Run Cypress Tests for a Local Project (Optional but Recommended)

The workflow is basically the same as seen above the only difference is that we are going to add a wait-on parameter that checks and waits for our local server to be up and running before running tests. By default, wait-on will retry for 60 seconds.

    name: Blog tests
    on: [push]
    jobs:
      cypress-run:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v1
          - name: Run blog test
            uses: cypress-io/github-action@v1
            with:
              start: npm start
              wait-on: 'http://localhost:3000'
              config: baseUrl=https://localhost:3000

I’ve stripped off some lines so you can focus on what is important for testing locally.

Notice how we’ve updated the baseUrl in the config parameter to point to a localhost endpoint. Ensure that you have an app running at port 3000 which you intend to test.

Send test results to Cypress dashboard for monitoring

Cypress dashboard is an option that provides details and visual representation of our test runs, their reports, status, and events that took place during execution. It basically gives you details of what happened when your tests ran.

The Cypress dashboard service is very useful when you are running test cases in a CI environment. We won’t be covering benefits or features provided by Cypress dashboard service in this article but for more information on that, click here.

How to setup a Cypress dashboard
Open the test runner and click on the runs tab of your project. Of course there will be no record of test runs visible because we are yet to set it up. Now click on the Connect to dashboard button.

You will be prompted to log in to the Cypress dashboard to be able to record your test. To do that, you can log in with your Google or Github account. You should see a success message after a successful login and you will be asked to provide the following details as seen below.

You can give your project a name - this can be changed anytime.
Select who owns the project - You can personally own it or create an organisation. I have taken ownership as seen above.
Finally, you need to decide if you want to make it a private or public project - as seen above, I have provided a public access to mine.

After providing the details, you can click the Set up project button. You should see a view explaining how to record your first run.

Note that your key MUST be confidential and private to you. I left mine for demo purpose and has deactivated it.

Recording Test Runs To your Dashboard
Firstly, Cypress will, by default, auto-populate your cypress.json file with a unique project ID as seen above. You can check your cypress.json file to verify this.

Secondly, we won’t be running the above mentioned command in the terminal, we are going to set the record key as an environmental variable in the project’s repository on Github. Click on the Settings button.

Click on the Secrets tab on the left hand menu to navigate to the Secrets page then click on New secret button on the right hand side of the screen.

You should see a screen as shown below. Type in the name of your secret then copy the value of your record key from the runs tab of your test runner and paste it in the value field then click the Add secret button.

Update your workflow configuration to include a record field and a CYPRESS_RECORD_KEY env variable.

     steps:
        # - name: Checkout
        # - name: Setup npm package
       # - name: Run E2E test
        #  uses: cypress-io/github-action@v1
          with:
             start: npm start
             wait-on: 'http://localhost:3000'
             config: baseUrl=http://localhost:3000
            with:
              record: true
            env:
              CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

record: This tells Cypress to take video recording, screenshots and logs of all our test runs.
We are also passing our dashboard record key as an environment variable here. Cypress action by default runs the cypress run command for us. In addition to that if it sees a CYPRESS_RECORD_KEY and a record property set to true, it will automatically start recording the test.

Now we are all set!! Push to GitHub and as soon as the tests finish running, you should be able to see the details of the tests on the dashboard via the Runs tab of the test runner.

If you click on any record, it’s run will open in chrome. You’ll see a detailed record of test runs, number of test cases that passed or failed, videos, screenshots (for failed test cases), operating system on which the tests ran, duration, etc as shown below.

Yayyyyy!!! We finally have our dashboard up and running. If you made it to this point, CONGRATULATION!!