Skip to content

Requirements and setup for NEO

This guide is meant for anyone, with no technical or programming knowledge, who needs to get their computer ready to work with NEO. By the time you finish reading it, you'll be able to answer:

  • What do I need installed on my computer to be able to use NEO?
  • How do I get my AI assistant to "see" this project's skills, and how do I use them once they're available?
  • How do I configure Playwright, the engine the skills use to drive the browser?

IMPORTANT! This is an installation and setup guide (it's done just once per computer, or every time you start on a new project). To understand what a skill or a playbook is, or how to choose between the different working models, see the Playbooks vs Skills and Models guides.


1. The idea in a single sentence

NEO isn't a program you install and you're done — it's a folder with written instructions ("skills") that a compatible AI assistant (Claude Code, Codex, or GitHub Copilot), inside an editor called VSCode, knows how to read and run. For it to work, you need three things: the editor (VSCode), the assistant (Claude Code, Codex, or Copilot), and the tools the skills use behind the scenes (Node.js, Playwright, and optionally Java/Maven).

With that installed just once, you ask your assistant for everything else (read a story, put together a test plan, generate and run tests) in natural language.


2. Required technical stack — at a glance

This table summarizes everything you need to have installed. Points 3 to 5 explain, step by step, how to get each thing.

You need What is it for? Is it mandatory?
A computer with Windows, Mac, or Linux Where everything else runs Yes
VSCode (Visual Studio Code) The editor where you'll work together with your AI assistant Yes
Your AI assistant's extension/CLI (see the table in 2.1) The assistant that reads and runs the skills Yes
An account enabled for that assistant (see the table in 2.1) Without logging in, the assistant can't answer you at all Yes
Git To download (clone) the NEO repository (NEO-releases) and the test repository Yes
Node.js + npm The engine that runs Playwright (the most widely used test framework in this project) Yes, if the project uses Playwright
Playwright + its browsers It's what actually "drives" the browser to explore the app and run the tests Yes, if the project uses Playwright
Internet connection / company VPN To download the repo, the Playwright browsers, and connect to Jira/Azure DevOps if applicable Yes
Java (JDK 8+) and Apache Maven Only if the project uses Lippia (Java + Cucumber) instead of Playwright No — only for the Lippia stack
Google Chrome installed Only if the project uses Lippia (it needs a real system Chrome; the one Playwright downloads isn't enough) No — only for the Lippia stack

The rest of this guide assumes the most common case: a project that uses Playwright (JavaScript/TypeScript). If your project uses Lippia, at the end of section 5 there's a note with the extra requirements.

2.1 Which AI assistant can I use?

NEO doesn't depend on any particular assistant: any of these three works, because all three know how to read skills in SKILL.md format and connect to the same Playwright MCP server (.mcp.json). The only things that change between them are the extension/CLI to install, the account you sign in with, and the folder where each one looks for the skills.

Assistant Extension/CLI Account required Skills folder (in the test repository)
Claude Code "Claude Code" extension for VSCode (or the terminal CLI) Enabled Claude/Anthropic account .claude/skills/
Codex Codex extension/CLI Account enabled for Codex .codex/skills/
GitHub Copilot GitHub Copilot extension for VSCode GitHub account with Copilot enabled .copilot/skills/

The rest of this guide uses Claude Code as the reference example in the concrete steps (it's the one documented in the most detail today), but each step has a direct equivalent for Codex or Copilot by swapping the extension/account/folder according to this table.


3. Step by step: install the basics

3.1 Install VSCode

  1. Download it from code.visualstudio.com and follow the installer (next, next, finish).
  2. Open it once it's installed to confirm that it starts correctly.

3.2 Install your AI assistant

The steps below are for Claude Code. If you use Codex or Copilot, install the equivalent extension/CLI (see the table in 2.1) and follow that tool's own login flow — the rest of this guide (skills, Playwright, MCP) works the same way once the assistant is installed and logged in.

  1. In VSCode, open the extensions panel (the little squares icon in the left margin, or Ctrl+Shift+X).
  2. Search for "Claude Code for vs Code" and install it.
  3. When you open it for the first time, it will ask you to sign in with your Claude/Anthropic account — follow the login flow it suggests (the browser opens, you confirm, and you go back to VSCode).

IMPORTANT: If your user doesn't have access enabled yet, ask the technical team for it before continuing — without logging in, there's no way to use the assistant.

3.3 Install Git

Git is what lets you download ("clone") the project repositories.

  • Windows: download it from git-scm.com and install it with the default options (this also installs Git Bash, a terminal you'll need later).
  • Mac: it usually comes preinstalled; if not, xcode-select --install from the Terminal, or git-scm.com.

Check that it's installed: open a terminal (on Windows, search for "Git Bash") and type:

git --version

If it returns a version number, you're all set.

3.4 To clone the repositories you'll need

You'll work with at least two folders in VSCode, depending on the project:

  1. NEO-releases — where the skills and playbooks live.
  2. The test repository (for example, TechStore's) — where you'll generate and run the tests. It can be the same repository as the application's or, as in many projects, a separate one.

To get the link to the repository, follow these steps:

Go to GitLab (https://gitlab.crowdaronline.com/lippia/products/neo) once you've been given permissions to the project, click the repo you want to clone, for example "NEO-releases", press the "Code" button, and when it opens it will show you two options; copy the "Clone with HTTPS" or "Clone with SSH" one.

To clone the repository in VSCode, Ctrl+Shift+P → type "Git: Clone", which brings up an input field at the very top → paste the repository URL you copied → choose a folder on your computer → Open when it's done. (The same procedure is explained in more detail in last_version.md, section 6.)

3.5 Install Node.js and npm

Node.js is the engine Playwright needs in order to run. npm (Node Package Manager) comes included with Node.js — it isn't installed separately.

  1. Download the LTS version (the recommended one, not the "Current" one) from nodejs.org.
  2. Install it with the default options.

Check:

node --version
npm --version

Both commands must return a version number.


4. How to make the skills available to your AI assistant

With VSCode, your AI assistant, Git, and Node already installed, the missing step is telling the assistant where the NEO-releases skills are. Your assistant doesn't "guess" them — it needs to find them in a specific folder of the test repository.

4.1 How it works

Each skill is a folder with a SKILL.md file inside: written instructions so the assistant knows how to do a specific task (read a story, put together a test plan, generate tests, etc.). The NEO-releases repository contains an "INSTALL.md" file with all the steps to carry out (it complements this guide).

When a session starts, your assistant looks for the skills in this folder, inside the test repository (the repository where your automated tests live, which can be the same as the application's or a separate one):

<test-repository>/.claude/skills/

If you use Codex or Copilot instead of Claude Code, the logic is the same, replacing .claude with .codex or .copilot (according to the table in 2.1).

You don't need to copy the files by hand: NEO-releases includes a script that creates a shortcut (symlink) for each skill, pointing to the real folder inside NEO-releases. That way, when the technical team updates a skill and you do a pull on NEO-releases (see last_version.md), the change shows up on its own, without repeating any step. The script also links the playbooks into .claude/playbooks/ and copies into .claude/rules/ the rules the assistant needs to run them.

There's one script for each operating system. Both are run from the folder of the test repository (not NEO-releases). In both cases, replace <path-to-neo-releases> with the folder where you cloned NEO-releases (for example, ../NEO-releases if both repositories are in the same parent folder).

On Linux or Mac

  1. Open a terminal.
  2. Navigate to the folder of the test repository:

    cd /path/to/test-repository
    
  3. Run the NEO-releases script:

    bash <path-to-neo-releases>/symlink-skills-bash.sh
    
  4. Check that the shortcuts were created:

    ls -l .claude/skills/
    

    You should see a list with the name of each skill, pointing to the NEO-releases folder.

On Windows

  1. Open Git Bash with administrator privileges: search for "Git Bash" in the start menu, right-click it, and choose Run as administrator. Windows only allows creating symbolic links with administrator permissions. VSCode's integrated terminal won't work for this step, unless you opened VSCode as administrator.
  2. Navigate to the folder of the test repository:

    cd /path/to/test-repository
    
  3. Run the NEO-releases script:

    bash <path-to-neo-releases>/symlink-skills-win-git-bash.sh
    
  4. When it finishes, the script shows the list of linked skills. Each one must appear with the type <SYMLINKD> (symbolic link to a folder). If they appear as <DIR>, they're copies that won't be updated with git pull: delete the .claude/skills folder and run the script again from Git Bash as administrator.

The scripts create the links for Claude Code (the .claude/ folder). If you use Codex or Copilot on Windows, change ASSISTANT=claude to ASSISTANT=codex or ASSISTANT=copilot in symlink-skills-win-git-bash.sh before running it. The Linux or Mac script only creates .claude/ for now.

IMPORTANT: If you're using VSCode with the Claude Code extension, after creating the links you need to reload VSCode so the available skills can be seen.

4.3 Check that your assistant can see them

Open a session with your AI assistant on the test repository and write to it, in natural language:

List the available Neo skills

If the installation went well, your assistant will reply with the list of skills (lippia-neo-read-user-story, lippia-neo-create-test-plan, lippia-neo-meta-run-user-story-e2e, etc.).

4.4 Uninstall (if needed)

Since they're shortcuts, deleting them doesn't touch the NEO-releases repository. From the folder of the test repository:

rm -rf .claude/skills .claude/playbooks

5. How to configure Playwright

Playwright is the tool that actually opens a browser (Chrome, Firefox, etc.), navigates through the app under test, clicks, fills in forms, and checks results — it's the "executing arm" behind the skills when the project is configured with this framework.

5.1 Install the project dependencies

Navigate to the root folder of the test repository (where its package.json is, not NEO-releases) and run, in a terminal:

npm install

This downloads the libraries the project already has declared in its package.json (among them, @playwright/test).

IMPORTANT: npm install doesn't add @playwright/test on its own — if the project doesn't have it declared in package.json (in dependencies or devDependencies), you need to add it first (npm install @playwright/test, or ask lippia-neo-bootstrap-stack/lippia-neo-ci-bootstrap to check it). This applies both if you run this on your computer and in the CI pipeline: if the package isn't declared, npx playwright install ends up resolving an ad-hoc version different from the project's, and if the pipeline runs on an image without a root user (like the Crowdar engine's), adding --with-deps to that command fails outright (it needs root permissions that image doesn't have).

5.2 Install the Playwright browsers

Playwright needs its own copies of the browsers (it doesn't use the Chrome you already have installed on your computer):

npx playwright install

This step downloads the Chromium, Firefox, and WebKit binaries. You only need to run it once per computer (or when the project's Playwright version changes).

5.3 Install the browser for the exploration stage (MCP)

Besides running the tests, your assistant uses Playwright to explore the app manually before generating the tests (the lippia-neo-run-manual-testing skill). For that, it needs its own browser via MCP:

npx @playwright/mcp install-browser chrome-for-testing

⚠️ Watch out for version drift in @playwright/mcp@latest: this repo's .mcp.json starts the server with @playwright/mcp@latest, so each run can bring a different version of the package — and each version expects a different Chrome-for-Testing revision. If you already had a browser installed from an old run, an error like Browser "chrome-for-testing" is not installed; expected executable at ...\ms-playwright\chromium-<rev>\chrome-win64\chrome.exe may appear. The fix is to run the command above again to install the revision the error asks for — see the full details in playwright-mcp-setup.md (Incident 5).

5.4 What the .mcp.json file is (you don't need to touch it)

The NEO-releases repository already comes with a .mcp.json file with the Playwright MCP server configuration:

"playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"],
      "env": {}
}

You don't need to edit this — it already comes configured. It's simply how your assistant knows how to start the Playwright browser when a skill needs it. This file is the same for all three assistants (Claude Code, Codex, and Copilot) — nothing changes depending on which one you use.

If you get a connection error when using a skill that depends on the MCP (for example lippia-neo-run-manual-testing), see the playwright-mcp-setup guide — it covers the most common Playwright MCP configuration incidents and how to solve them.

5.5 Data for the environment under test (URL and credentials)

The skills need to know which URL to test against and with which user. This lives in a .env file (which is never pushed to the repository — it's in .gitignore), at the root of the test repository:

# .env
APP_BASE_URL=https://your-app-under-test.com
APP_USERNAME=test-user
APP_PASSWORD=test-password

If you don't have this file yet, the lippia-neo-bootstrap-stack skill can create it for you, asking you for this data the first time it configures the project.

Generated artifacts may still contain credentials

The skills are explicitly designed not to take the values from the .env file (or from the folder you defined) and leave them "hardcoded" in the code or the reports they generate. But AI isn't perfect: in practice, credentials, tokens, or sensitive data may end up leaked in the test code, in the reports, in screenshots, or in other generated artifacts.

That's why, before pushing these artifacts to a shared repository or distributing them, review them (or define a checkpoint/review step in your flow) to confirm that no sensitive data was left exposed.

5.6 The qa-stack.yaml file

It's the project's "technical sheet": it tells the skills that the framework is playwright, which folder the tests are in, where the reports are saved, etc. You don't need to write it by hand.

To understand what this playbook does step by step before running it, read the new-project-bootstrap guide.

5.7 Quick Playwright checklist

node --version && npm --version    # Node and npm installed
npm install                        # project dependencies
npx playwright install             # navegadores de Playwright
npx @playwright/mcp install-browser chrome-for-testing   # browser for exploration

If all four commands run without errors, Playwright is ready for the skills to generate and run tests.

Does your project use Lippia (Java + Cucumber) instead of Playwright? Then, instead of this section, you need: a JDK 8+, Apache Maven 3.6+, access to Crowdar's Nexus repositories, and a real Google Chrome installed on the system (the one Playwright downloads isn't enough). The full details for this case are in the INSTALL.md of the NEO-releases repo.


6. Visual summary of the complete flow

Step-by-step setup: from installing VSCode and Claude Code to being able to ask for any QA work in natural language, with the progress percentage at each stage

The diagram uses Claude Code as an illustrative example, but the flow (install the editor, install the assistant, make the skills available, ask for work in natural language) is the same if you use Codex or Copilot.


7. Common problems (and what to do)

What you see Why it may happen What to do
Your assistant replies that it can't find any skill The symlink wasn't created, or it was created in a folder other than the test repository's Repeat step 4.2 from the folder of the test repository and check with ls -l .claude/skills/ (or your assistant's equivalent folder — see 2.1)
The symlink script (symlink-skills-win-git-bash.sh) throws errors on Windows You ran it from the Windows terminal (cmd.exe or PowerShell) instead of Git Bash, or you opened Git Bash without administrator permissions Open Git Bash with Run as administrator and run the script again from the folder of the test repository (step 4.2)
npx playwright install takes a long time or fails It's downloading the browsers for the first time and depends on your connection Wait for it to finish; if it fails due to the network, check your connection/VPN and try again
A test fails with a browser-not-found error You haven't run npx playwright install or npx @playwright/mcp install-browser yet Run both commands (sections 5.2 and 5.3)
Error Browser "chrome-for-testing" is not installed; expected executable at ...chromium-<rev>... even though you had already installed the browser before @playwright/mcp@latest brought a new version that expects a different Chrome-for-Testing revision than the one you have installed (see section 5.3) Run npx @playwright/mcp@latest install-browser chrome-for-testing to install the revision the error asks for
In the CI pipeline, npx playwright install fails with su: Authentication failure (or similar, asking for the root password) --with-deps was added to the command on a runner that runs as a non-root user (like the Crowdar engine's image) — that image already comes with the system dependencies installed out of the box Remove --with-deps from the command in CI; npm install && npx playwright install <browser> is enough
A skill with an adapter (lippia-neo-generate-test-suite, lippia-neo-run-and-heal) says configuration is missing There's no qa-stack.yaml at the root of the test repository Ask your assistant: "use lippia-neo-bootstrap-stack to generate qa-stack.yaml"
The tests can't find the app's URL or credentials The .env file is missing or is missing variables Create/complete .env at the root of the project with APP_BASE_URL, APP_USERNAME, APP_PASSWORD (section 5.5)
Your assistant doesn't respond at all / keeps asking you to sign in The account (Claude/Anthropic, Codex, or GitHub) didn't stay logged in, or doesn't have access enabled Repeat the login from the extension/CLI (step 3.2); if the problem persists, check with the technical team about access