Node js project Setup Guide

This guide will walk you through setting up Node.js on both Mac and Windows, creating a package.json file, and installing the kogi JavaScript SDK.

Installing Node.js

On Mac

1. Check if Node.js is already installed: Open Terminal and run:

node --version
npm --version

2. If not installed, download Node.js:

• Visit nodejs.org
• Download the macOS installer (LTS version recommended)
• Run the installer and follow the prompts

3. Verify installation:

node --version
npm --version

On Windows

1. Check if Node.js is already installed: Open Command Prompt or PowerShell and run:

node --version
npm --version

2. If not installed, download Node.js:

• Visit nodejs.org
• Download the Windows installer (LTS version recommended)
• Run the installer and follow the prompts
• Make sure to check "Automatically install the necessary tools" if prompted

3. Verify installation:

node --version
npm --version

Creating a New Project

Initialize a New Project

1. Create a project directory:

# Mac/Linux Terminal
mkdir my-kogi-project
cd my-kogi-project

# Windows Command Prompt
mkdir my-kogi-project
cd my-kogi-project

# Windows PowerShell
New-Item -ItemType Directory -Name my-kogi-project
cd my-kogi-project

2. Initialize the project with npm:

npm init -y

This creates a package.json file with default values.

3. (Optional) Edit package.json: You can manually edit the package.json file to add details about your project:

{
  "name": "my-kogi-project",
  "version": "1.0.0",
  "description": "A project using kogiQA SDK",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ["kogi", "testing", "automation"],
  "author": "Your Name",
  "license": "ISC"
}

Installing the kogi SDK

Install kogi as a Dependency

Run the following command in your project directory:

npm install kogi

This will:

• Add kogi to your package.json dependencies
• Create a package-lock.json file (locks dependency versions)
• Create a node_modules folder with the kogi SDK and its dependencies

Verify Installation

You can verify the installation by checking your package.json:

{
  "dependencies": {
    "kogi": "^x.x.x"
  }
}

Creating Your First Test Script

Create a new file called test.js in your project directory:

import {Browser} from "kogi";

(async () => {
    // Replace with your actual access token
    const browser = await Browser.start("YOUR_ACCESS_TOKEN", "chrome", "My First Test");

    try {
        await browser.navigate("https://example.com");
        await browser.hasText("Example");
        console.log("Test passed!");
    } catch (error) {
        console.error("Test failed:", error);
    } finally {
        await browser.close();
    }
})();

Run your test:

node test.js

Project Structure

After completing the setup, your project structure should look like this:

my-kogi-project/
├── node_modules/
├── package.json
├── package-lock.json
└── test.js

Troubleshooting

Common Issues

1. Permission errors on Mac/Linux: If you get EACCES permission errors, you might need to:

sudo chown -R $(whoami) ~/.npm

2. Command not found: If node or npm commands aren't recognized, ensure they were added to your PATH during installation.

3. Version conflicts: If you have multiple Node.js versions, consider using a version manager:

• Mac: Use nvm (Node Version Manager)
• Windows: Use nvm-windows

Using nvm (Mac/Linux)

To install and use nvm:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal or run:
source ~/.bashrc

# Install and use the latest LTS Node.js
nvm install --lts
nvm use --lts

Next Steps

Now that you have the kogi SDK installed, you can:

1. Learn the API to understand all available methods
2. Create more complex test scenarios
3. Integrate kogi tests into your CI/CD pipeline
4. Explore advanced features like email testing and custom assertions