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 SkillsandModelsguides.
1. The idea in a single sentence
NEOisn'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
- Download it from code.visualstudio.com and follow the installer (next, next, finish).
- 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.
- In VSCode, open the extensions panel (the little squares icon in the left margin, or
Ctrl+Shift+X). - Search for "Claude Code for vs Code" and install it.
- 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 --installfrom 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:
NEO-releases— where the skills and playbooks live.- 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.
- Download the LTS version (the recommended one, not the "Current" one) from nodejs.org.
- 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
.claudewith.codexor.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.
4.2 Link the skills to the test repository
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
- Open a terminal.
-
Navigate to the folder of the test repository:
cd /path/to/test-repository -
Run the
NEO-releasesscript:bash <path-to-neo-releases>/symlink-skills-bash.sh -
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-releasesfolder.
On Windows
- 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.
-
Navigate to the folder of the test repository:
cd /path/to/test-repository -
Run the
NEO-releasesscript:bash <path-to-neo-releases>/symlink-skills-win-git-bash.sh -
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 withgit pull: delete the.claude/skillsfolder 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, changeASSISTANT=claudetoASSISTANT=codexorASSISTANT=copilotinsymlink-skills-win-git-bash.shbefore 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 installdoesn't add@playwright/teston its own — if the project doesn't have it declared inpackage.json(independenciesordevDependencies), you need to add it first (npm install @playwright/test, or asklippia-neo-bootstrap-stack/lippia-neo-ci-bootstrapto 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 installends 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-depsto 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.jsonstarts 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 likeBrowser "chrome-for-testing" is not installed; expected executable at ...\ms-playwright\chromium-<rev>\chrome-win64\chrome.exemay appear. The fix is to run the command above again to install the revision the error asks for — see the full details inplaywright-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 theplaywright-mcp-setupguide — 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-bootstrapguide.
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 theINSTALL.mdof theNEO-releasesrepo.
6. Visual summary of the complete flow
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 |