Automatic Regression Testing Kit (ARTK)

ARTK is a standardized kit for building and maintaining automated regression testing suites using Playwright. It works through GitHub Copilot slash commands that guide you from discovery to implementation.

Quick Start

Unix/macOS/Linux:

# 1. Install ARTK to your project
/Users/chaouachimehdi/IdeaProjects/ARTK/scripts/bootstrap.sh .

# 2. Open VS Code with GitHub Copilot
# 3. In Copilot Chat, run:
/artk.init-playbook

Windows (PowerShell):

# 1. Install ARTK to your project
C:\Users\...\ARTK\scripts\bootstrap.ps1 .

# 2. Open VS Code with GitHub Copilot
# 3. In Copilot Chat, run:
/artk.init-playbook

Workflow (Prompts Only)

All work is done through Copilot slash commands. No CLI required.

┌─────────────────────────────────────────────────────────────────────────┐
│                           ARTK Workflow                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  SETUP (one command does everything)                                    │
│  ─────                                                                  │
│  /artk.init-playbook     Bootstrap + Playbook + Journey System          │
│                          (use journeySystem=false to skip backlog)      │
│                                                                         │
│  DISCOVERY                                                              │
│  ─────────                                                              │
│  /artk.discover-foundation   Analyze app + build Playwright harness     │
│  /artk.journey-propose       Auto-propose Journeys from discovery       │
│                                                                         │
│  TESTABILITY (recommended before implementation)                        │
│  ─────────────────────────────────────────────                          │
│  /artk.testid-audit        Audit selectors + add stable test hooks       │
│                                                                         │
│  JOURNEY LIFECYCLE                                                      │
│  ─────────────────                                                      │
│  /artk.journey-define    Create Journey (proposed → defined)            │
│  /artk.journey-clarify   Add machine hints (defined → clarified)        │
│  /artk.journey-implement Generate Playwright tests (→ implemented)      │
│  /artk.journey-validate  Static validation gate                         │
│  /artk.journey-verify    Run tests + auto-heal failures                 │
│                                                                         │
│  MAINTENANCE (coming soon)                                              │
│  ─────────────────────────                                              │
│  /artk.journey-maintain  Quarantine flaky, deprecate obsolete           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Installation

Unix/macOS/Linux:

/Users/chaouachimehdi/IdeaProjects/ARTK/scripts/bootstrap.sh /path/to/your-project

Windows (PowerShell):

C:\Users\...\ARTK\scripts\bootstrap.ps1 C:\path\to\your-project

What gets installed:

artk-e2e/ - E2E workspace (Playwright config, tests, journeys)
artk-e2e/vendor/artk-core/ - @artk/core library (auth, config, fixtures)
.github/prompts/ - Copilot slash commands (all /artk.* commands)
.artk/context.json - ARTK context metadata

VS Code prompt UX: ARTK prompt files include handoffs so Copilot can show clickable next commands, and the bootstrap script adds chat.promptFilesRecommendations to .vscode/settings.json to surface /artk.* commands as recommended actions at chat start.

Browser Selection

Bootstrap detects available browsers and writes the chosen channel and strategy to artk-e2e/artk.config.yml:

browsers:
  enabled:
    - chromium
  channel: bundled
  strategy: auto

Strategies: auto, prefer-bundled, prefer-system, bundled-only, system-only. Metadata is recorded in .artk/context.json, and generated Playwright configs validate the selected channel at startup.

Copilot Slash Commands

Setup Command

/artk.init-playbook - Bootstrap ARTK + Playbook + Journey System (all-in-one)

Note: Use journeySystem=false to skip BACKLOG.md automation if not needed.

Discovery Commands

/artk.discover-foundation - Analyze app routes, auth, testability + build harness
/artk.journey-propose - Auto-propose Journeys from discovery results

Testability Command

/artk.testid-audit - Audit brittle selectors and recommend (or apply) stable hooks

Journey Lifecycle Commands

/artk.journey-define - Create a new Journey file with frontmatter
/artk.journey-clarify - Add machine hints for deterministic execution
/artk.journey-implement - Generate Playwright tests from Journey
/artk.journey-validate - Static validation (schema, tags, lint)
/artk.journey-verify - Run tests, collect evidence, auto-heal failures

Maintenance Command (Coming Soon)

/artk.journey-maintain - Quarantine flaky tests, deprecate obsolete Journeys

Typical Usage Flow

# 1. Install ARTK
/Users/chaouachimehdi/IdeaProjects/ARTK/scripts/bootstrap.sh .

# 2. In VS Code Copilot Chat:
/artk.init-playbook             # Bootstrap project + guardrails
/artk.discover-foundation       # Analyze app + create harness
/artk.journey-propose           # Get suggested Journeys
/artk.testid-audit mode=report  # Audit selectors and plan stable test hooks

# 3. For each Journey:
/artk.journey-define id=JRN-0001 title="User Login"
/artk.journey-clarify id=JRN-0001
/artk.journey-implement id=JRN-0001
/artk.journey-validate id=JRN-0001
/artk.journey-verify id=JRN-0001

Journey File Format

Journeys are markdown files with YAML frontmatter:

---
id: JRN-0001
title: User Login
status: clarified
tier: smoke
actor: registered_user
scope: authentication
modules:
  foundation:
    - auth/login-page
  features: []
completion:
  - type: url
    value: /dashboard
---

# User Login Journey

## Context
A registered user authenticates to access the dashboard.

## Acceptance Criteria
- [ ] User can enter email and password
- [ ] Login redirects to dashboard

## Steps

### Step 1: Navigate to Login
Navigate to the login page.

**Machine Hints:**
- action: goto
- url: /login

Docs

Journey proposal metadata fields: docs/JOURNEY_PROPOSAL_FIELDS.md

Journey Lifecycle

proposed → defined → clarified → implemented
                                      ↓
                              quarantined (flaky)
                                      ↓
                              deprecated (obsolete)

proposed - Initial idea, minimal structure
defined - Has frontmatter + acceptance criteria
clarified - Has machine hints for each step
implemented - Has linked tests, validated, verified
quarantined - Requires owner, statusReason, links.issues[]
deprecated - Requires statusReason

Documentation

docs/ARTK_Master_Launch_Document_v0.7.md - Full specification
docs/ARTK_Journey_Lifecycle_v0.1.md - Journey status lifecycle
docs/ARTK_Module_Architecture.md - ESM/CommonJS support and module system decisions
docs/ARTK_Core_v1_Specification.md - @artk/core library specification
docs/TESTID_AUDIT_DISCOVERY_GUIDANCE.md - When to re-run discovery after testid audits

Repository Structure

ARTK/
├── scripts/
│   └── bootstrap.sh           # Main installer
├── prompts/                    # Copilot slash commands
│   ├── artk.init-playbook.md       # Setup (includes Journey System)
│   ├── artk.discover-foundation.md
│   ├── artk.journey-propose.md
│   ├── artk.journey-define.md
│   ├── artk.journey-clarify.md
│   ├── artk.journey-implement.md
│   ├── artk.journey-validate.md
│   ├── artk.journey-verify.md
│   └── artk.testid-audit.md
├── core/typescript/
│   ├── src/                    # @artk/core source
│   └── autogen/                # @artk/core-autogen source
└── docs/                       # Specifications

FAQ

npm can't download packages behind my corporate proxy

Problem: npm install fails with 403 Forbidden errors when downloading packages, even though JFrog authentication is configured correctly.

Root cause: Your corporate proxy may block S3 URLs. JFrog Artifactory stores package tarballs on AWS S3 and redirects downloads there. If your proxy blocks "Cloud Infrastructure" or S3 domains, the redirect fails.

Solution: Use your company's internal Artifactory domain (which bypasses the proxy) instead of the external JFrog domain.

Check your proxy bypass list:

# Windows
netsh winhttp show proxy

Look for domains like *.xxxxx.io or *.xxxxx.com in the exception list.

Fix your npm configuration:

# 1. Backup current config
copy $env:USERPROFILE\.npmrc $env:USERPROFILE\.npmrc.backup

# 2. Switch to internal Artifactory domain (bypasses proxy)
# Use: artifactory.xxxxx.io (internal) instead of xxxxx.jfrog.io (external)
npm config set registry https://artifactory.xxxxx.io/artifactory/api/npm/npm/

# 3. Remove explicit proxy settings (let system handle it)
npm config delete proxy
npm config delete https-proxy

# 4. Test
npm pack @ts-morph/common@0.25.0

Key insight: Internal domains like artifactory.xxxxx.io typically match proxy bypass rules (*.xxxxx.io), so traffic goes direct. External domains like xxxxx.jfrog.io go through the proxy, where S3 redirects may be blocked.

If you still have issues:

# Check for lingering proxy settings
npm config list
echo "HTTP_PROXY: $env:HTTP_PROXY"
echo "HTTPS_PROXY: $env:HTTPS_PROXY"

# View your .npmrc directly
Get-Content $env:USERPROFILE\.npmrc

Name		Name	Last commit message	Last commit date
Latest commit History 309 Commits
.claude		.claude
.codex/commands		.codex/commands
.github		.github
.husky		.husky
.specify		.specify
bazinga		bazinga
cli		cli
core		core
demo		demo
docs		docs
packages/cli		packages/cli
patches		patches
prompts		prompts
research		research
scripts		scripts
specs		specs
templates		templates
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.md		README.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Automatic Regression Testing Kit (ARTK)

Quick Start

Workflow (Prompts Only)

Installation

Browser Selection

Copilot Slash Commands

Setup Command

Discovery Commands

Testability Command

Journey Lifecycle Commands

Maintenance Command (Coming Soon)

Typical Usage Flow

Journey File Format

Docs

Journey Lifecycle

Documentation

Repository Structure

FAQ

npm can't download packages behind my corporate proxy

About

Uh oh!

Releases 2

Packages

Contributors 3

Uh oh!

Languages

mehdic/ARTK

Folders and files

Latest commit

History

Repository files navigation

Automatic Regression Testing Kit (ARTK)

Quick Start

Workflow (Prompts Only)

Installation

Browser Selection

Copilot Slash Commands

Setup Command

Discovery Commands

Testability Command

Journey Lifecycle Commands

Maintenance Command (Coming Soon)

Typical Usage Flow

Journey File Format

Docs

Journey Lifecycle

Documentation

Repository Structure

FAQ

npm can't download packages behind my corporate proxy

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Contributors 3

Uh oh!

Languages

Packages