testflow-ai 0.3.0 → 0.4.0

package/README.md

@@ -2,15 +2,19 @@
 
 # 🧪 testflow-ai
 
-**Declarative API testing powered by YAML flows**
+**YAML API flows + optional LLM assertions (local Ollama or cloud)**
 
-*Version-controlled • Human-readable • AI-friendly*
+*Version-controlled • CI/CD-ready • Human-readable*
 
 [![npm version](https://img.shields.io/npm/v/testflow-ai.svg?style=for-the-badge&color=blue)](https://www.npmjs.com/package/testflow-ai)
 [![npm downloads](https://img.shields.io/npm/dm/testflow-ai.svg?style=for-the-badge&color=green)](https://www.npmjs.com/package/testflow-ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green.svg?style=for-the-badge)](https://nodejs.org)
 
+✅ **Multi-step flows** (create → capture → reuse → assert)  
+🤖 **Assert "hard" responses with AI** (privacy-first via Ollama)  
+📄 **Keep API context in Markdown** (great for humans + AI agents)
+
 [📖 Documentation](#-documentation) • [🚀 Quick Start](#-quick-start) • [💻 Examples](#-real-world-example) • [🤖 AI Providers](#-ai-powered-evaluation)
 
 </div>
@@ -19,9 +23,59 @@
 
 ## 🎯 What is testflow-ai?
 
-**testflow-ai** lets you define API tests in YAML files, run them from the command line or as a library, and use AI models (local or cloud) for intelligent assertions. No GUI, no vendor lock-in, works with any HTTP/GraphQL API.
+**testflow-ai** lets you describe API scenarios in YAML files, run them from the command line or as a library, and (optionally) ask an AI model to judge complex responses. No GUI, no vendor lock‑in, and it works with any HTTP/GraphQL API.
+
+> **💡 Born from real-world frustration:**  
+> After days of testing APIs with Postman and burning tokens with ChatGPT, I built this to centralize tests in version-controlled YAML files with local AI support.  
+> I wanted something that felt more like a **test agent**: a tool that could **create data, mutate it, delete it, and walk full flows end‑to‑end**, but defined in plain files, close to the code, and easy to run in CI.  
+> **testflow-ai** is that tool: a thin engine that turns YAML flows into real HTTP calls, variable captures, assertions, and (if you want) AI‑powered checks.
+
+---
+
+## ✨ Why it's different
+
+Most API testing tools are either **GUI-first** (collections) or **code-first** (JS/TS test code).  
+**testflow-ai** is **flow-first**: readable YAML that runs in CI — with an optional AI judge when classic assertions aren't enough.
+
+**What you get:**
+
+- **Flow engine**: multi-step scenarios with capture + interpolation (CRUD, auth, webhooks, background jobs)
+- **AI assertions**: validate complex text/structured responses with natural language checks (Ollama/OpenAI/Anthropic)
+- **Context-as-docs**: a Markdown file that explains base URLs, endpoints, and rules — perfect input for AI agents too
+
+---
+
+## ✅ When to use testflow-ai
+
+- You want **version-controlled API E2E flows** (not a GUI collection)
+- You need **multi-step chaining** (create → capture id → update → verify)
+- You want **CI/CD-ready output** (console/json/markdown + exit codes + no external deps)
+- You sometimes need an **AI judge** for fuzzy checks (content quality, summaries, "is this coherent?")
+
+## 🚫 When NOT to use it
+
+- You only need **schema/property-based fuzzing** from OpenAPI
+- You prefer **writing tests in code** (Jest/Vitest) with full programmatic control
+- You need **browser/UI testing** (Playwright/Cypress territory)
+
+---
+
+## 🆚 What testflow-ai optimizes for
 
-> **💡 Born from real-world frustration:** After months of testing APIs with Postman and burning tokens with ChatGPT, I built this to centralize tests in version-controlled YAML files with local AI support.
+<div align="center">
+
+| Goal | testflow-ai |
+|:----:|:-----------:|
+| Human-readable flows in Git | ✅ |
+| Multi-step chaining + captures | ✅ |
+| CI/CD-ready (exit codes, JSON) | ✅ |
+| Optional AI-based assertions | ✅ |
+| GUI collections | ❌ (not a goal) |
+| Full code-based test suites | ❌ (use your test framework) |
+
+</div>
+
+---
 
 ### ✨ Key Features
 
@@ -46,63 +100,63 @@
 
 ## 🚀 Quick Start
 
-### 1️⃣ Install
-
 ```bash
-npm install testflow-ai
+npm i -D testflow-ai
 ```
 
-### 2️⃣ Create a test flow
+**Create `context.md`:**
 
-Create `tests/health.yaml`:
+```markdown
+# My API
+
+## Base URLs
+- api: http://localhost:3000
+```
+
+**Create `tests/todo.yaml`:**
 
 ```yaml
-name: Health Check
+name: Todo flow
 tags: [smoke]
 
 steps:
-  - name: Ping API
+  - name: Create todo
     request:
-      method: GET
-      url: http://localhost:3000/health
+      method: POST
+      url: "{api}/todos"
+      headers:
+        Content-Type: application/json
+      body:
+        title: "Buy milk"
+        completed: false
+    capture:
+      - name: todoId
+        path: data.id
     assertions:
       - path: status
         operator: equals
-        value: 200
+        value: 201
+
+  - name: Fetch todo
+    request:
+      method: GET
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: data.title
+        operator: equals
+        value: "Buy milk"
 ```
 
-### 3️⃣ Run
+**Run:**
 
 ```bash
-npx testflow tests/health.yaml
+npx testflow --context ./context.md tests/todo.yaml
 ```
 
 **That's it.** No config files, no GUI, no account.
 
 ---
 
-## 💡 Why testflow-ai?
-
-I was building a backend that started as a simple API and grew into a system with GraphQL, async workers, state machines, and AI-powered evaluations.
-
-Testing started simple — a few requests in Postman. Then the project scaled:
-
-<div align="center">
-
-| ❌ Problem | ✅ Solution |
-|:----------:|:-----------:|
-| **Postman / Insomnia** became unmanageable | YAML files in version control |
-| **IDE AI assistants** burned tokens, lost context | Local AI via Ollama (free, private) |
-| **MCP servers** required complex setup | Zero dependencies beyond Node.js |
-| **Manual token copying** between requests | Automatic variable capture |
-| **No CI/CD integration** | JSON output, exit codes, GitHub Actions ready |
-
-</div>
-
-**testflow-ai** solves all of this.
-
----
-
 ## 📦 Installation
 
 ```bash
@@ -167,23 +221,26 @@ process.exit(report.failedFlows > 0 ? 1 : 0);
 
 ---
 
-## 💻 Real-World Example
+<details>
+<summary><b>💻 Real-World Example</b> (click to expand)</summary>
 
-Here's how we use it in production at [educational-rewards](https://github.com/carbajalmarcos/educational-rewards):
+Here's a complete example using a Todo List API:
 
 ### Project Structure
 
 ```
-tests/declarative/
-├── index.ts              # Test runner
-├── context.md            # API context
-└── flows/
-    ├── health-check.yaml
-    ├── complete-reward-flow.yaml
-    └── submission-attempts.yaml
+my-api/
+├── tests/
+│   ├── index.ts              # Test runner
+│   ├── context.md            # API context
+│   └── flows/
+│       ├── health-check.yaml
+│       ├── todo-crud.yaml
+│       └── todo-complete-flow.yaml
+└── package.json
 ```
 
-### Test Runner (`index.ts`)
+### Test Runner (`tests/index.ts`)
 
 ```typescript
 import { runTests, type RunnerOptions } from 'testflow-ai';
@@ -205,55 +262,86 @@ async function main() {
 main();
 ```
 
-### Context File (`context.md`)
+### Context File (`tests/context.md`)
 
 ```markdown
-# Mambita API Context
+# Todo List API
+
+## Description
+A simple REST API for managing todo items.
 
 ## Base URLs
+- api: http://localhost:3000
 - graphql: http://localhost:3000/graphql
-- tasks: http://localhost:8000
 
 ## Endpoints
+- POST /todos - Create a new todo
+- GET /todos/:id - Get todo by ID
+- PUT /todos/:id - Update todo
+- DELETE /todos/:id - Delete todo
 - POST /graphql - GraphQL endpoint
-- POST /api/v1/pool/seed - Seed task pool
 ```
 
-### Test Flow (`flows/complete-reward-flow.yaml`)
+### Test Flow (`tests/flows/todo-crud.yaml`)
 
 ```yaml
-name: Complete Reward Flow (E2E)
-tags: [e2e, reward]
+name: Todo CRUD Flow
+tags: [todos, crud, smoke]
 
 steps:
-  - name: Start reward
+  - name: Create todo
     request:
       method: POST
-      url: "{graphql}"
-      graphql:
-        query: |
-          mutation StartReward($input: StartRewardInput!) {
-            startReward(input: $input) {
-              id
-              state
-              taskInstances { id state }
-            }
-          }
-        variables:
-          input:
-            childId: "${childId}"
-            catalogRewardId: "${catalogItemId}"
+      url: "{api}/todos"
+      headers:
+        Content-Type: application/json
+      body:
+        title: "Buy groceries"
+        completed: false
     capture:
-      - name: rewardId
-        path: data.startReward.id
+      - name: todoId
+        path: data.id
+    assertions:
+      - path: status
+        operator: equals
+        value: 201
+      - path: data.title
+        operator: equals
+        value: "Buy groceries"
+
+  - name: Get todo
+    request:
+      method: GET
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: data.id
+        operator: equals
+        value: "${todoId}"
+
+  - name: Update todo
+    request:
+      method: PUT
+      url: "{api}/todos/${todoId}"
+      headers:
+        Content-Type: application/json
+      body:
+        completed: true
+    assertions:
+      - path: data.completed
+        operator: equals
+        value: true
 ```
 
 ### Running Tests
 
 ```bash
-pnpm testflow:run              # All tests
-pnpm testflow:smoke            # Smoke tests only
-pnpm testflow submission-attempts  # Specific flow
+# Add to package.json scripts:
+"test:e2e": "ts-node tests/index.ts"
+"test:smoke": "ts-node tests/index.ts --tags=smoke"
+
+# Then run:
+npm run test:e2e
+npm run test:smoke
 ```
 
 ### Advanced usage
@@ -276,9 +364,12 @@ const executor = new FlowExecutor(context, true);
 const result = await executor.executeFlow(flow);
 ```
 
+</details>
+
 ---
 
-## 📝 Test Flow Reference
+<details>
+<summary><b>📝 Test Flow Reference</b> (click to expand)</summary>
 
 ### Basic structure
 
@@ -399,9 +490,12 @@ steps:
         value: "COMPLETED"
 ```
 
+</details>
+
 ---
 
-## ✅ Assertions
+<details>
+<summary><b>✅ Assertions</b> (click to expand)</summary>
 
 <div align="center">
 
@@ -427,6 +521,8 @@ steps:
 - `data.field` — response body field
 - `data.items[0].id` — array access
 
+</details>
+
 ---
 
 ## 🤖 AI-Powered Evaluation
@@ -568,9 +664,82 @@ steps:
 
 > **🔒 Privacy note:** Ollama runs entirely locally. OpenAI and Anthropic send data to their APIs. Choose based on your privacy requirements.
 
+### 🤖 AI assertions in CI (recommended settings)
+
+AI checks can be non-deterministic. For CI, prefer:
+
+- **Deterministic settings** (e.g. `temperature: 0` for OpenAI/Anthropic)
+- **Short, specific prompts** (avoid vague questions)
+- **Stable models** (avoid preview/beta models)
+
+Example:
+
+```typescript
+ai: {
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  // OpenAI doesn't expose temperature in our API yet, but use stable models
+}
+```
+
 ---
 
-## 📄 Context Files
+<details>
+<summary><b>🔒 Security & secrets</b> (click to expand)</summary>
+
+- **Avoid committing API keys.** Use environment variables (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).
+- The runner **redacts** common secret fields in logs (Authorization headers, tokens, cookies) when verbose mode is enabled.
+- Keep sensitive data out of YAML files — use environment variable interpolation or context files with `.gitignore`.
+
+**Example:**
+
+```yaml
+headers:
+  Authorization: "Bearer ${API_TOKEN}"  # Use env vars
+```
+
+**Best practices:**
+
+- Store secrets in `.env` files (add to `.gitignore`)
+- Use context files for non-sensitive config (base URLs, endpoints)
+- Never commit API keys or tokens in YAML files
+
+</details>
+
+---
+
+<details>
+<summary><b>🧩 YAML schema & autocomplete (VSCode)</b> (click to expand)</summary>
+
+We provide a JSON Schema for `*.yaml` test flows so you get autocomplete + validation in editors.
+
+**VSCode setup** (`.vscode/settings.json`):
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/carbajalmarcos/testflow-ai/main/schemas/testflow.schema.json": [
+      "tests/**/*.yaml",
+      "**/*.testflow.yaml"
+    ]
+  }
+}
+```
+
+This gives you:
+
+- ✅ Autocomplete for `name`, `steps`, `request`, `assertions`, etc.
+- ✅ Validation for required fields and types
+- ✅ Hover documentation for operators and options
+
+> **Note:** JSON Schema coming in a future release. For now, TypeScript types provide autocomplete via `import type { TestFlow } from 'testflow-ai'`.
+
+</details>
+
+---
+
+<details>
+<summary><b>📄 Context Files</b> (click to expand)</summary>
 
 Define your project context in Markdown. The runner uses it to resolve `{baseUrlKey}` references in your YAML flows.
 
@@ -599,15 +768,24 @@ Brief description of your API.
 - model: llama3.2:3b
 ```
 
+</details>
+
 ---
 
-## 🔄 CI/CD Integration
+<details>
+<summary><b>🔄 CI/CD Integration</b> (click to expand)</summary>
+
+**testflow-ai** works in any CI/CD pipeline:
+
+- Exit code `0` = success, `1` = failure (CI will fail automatically)
+- JSON output: `--format json` for parsing results
+- Tag filtering: `--tags smoke` for faster runs
 
 ### GitHub Actions
 
 ```yaml
 jobs:
-  api-tests:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -615,22 +793,19 @@ jobs:
         with:
           node-version: '20'
       - run: npm ci
+      - run: npm install -D testflow-ai
       - run: npm run start:server &
-      - run: npx testflow --dir ./tests --context ./context.md --format json > results.json
-      - uses: actions/upload-artifact@v4
-        with:
-          name: test-results
-          path: results.json
+      - run: npx testflow --dir ./tests --context ./context.md
 ```
 
-**Exit codes:**
+That's it. If tests fail, the job fails automatically (exit code 1).
 
-- `0` — all flows passed
-- `1` — one or more flows failed
+</details>
 
 ---
 
-## 📊 Output Examples
+<details>
+<summary><b>📊 Output Examples</b> (click to expand)</summary>
 
 ### Console Output
 
@@ -665,9 +840,12 @@ Narrative:
 ══════════════════════════════════════════════════════════════
 ```
 
+</details>
+
 ---
 
-## 🗺️ Roadmap
+<details>
+<summary><b>🗺️ Roadmap</b> (click to expand)</summary>
 
 - [ ] Database assertions (verify records directly via SQL)
 - [ ] gRPC / RPC support
@@ -677,16 +855,30 @@ Narrative:
 - [ ] HTML report output
 - [ ] `testflow init` wizard
 
+</details>
+
 ---
 
 ## 📚 Examples
 
 See the [`examples/`](./examples) directory for:
 
-- REST CRUD flows
-- GraphQL queries and mutations
-- Authentication flows
-- Context file templates
+- **Todo List CRUD** (`todo-crud.yaml`) - Complete REST CRUD flow
+- **Todo GraphQL** (`todo-graphql.yaml`) - GraphQL mutations and queries
+- **REST CRUD** (`rest-crud.yaml`) - User management example
+- **GraphQL Flow** (`graphql-flow.yaml`) - GraphQL with variable capture
+- **Auth Flow** (`auth-flow.yaml`) - Authentication and protected routes
+- **Context Files** (`context.md`, `todo-list-context.md`) - API context templates
+
+**Quick start with examples:**
+
+```bash
+# Run specific example
+npx testflow --context ./examples/todo-list-context.md ./examples/todo-crud.yaml
+
+# Run all examples in directory
+npx testflow --dir ./examples --context ./examples/context.md
+```
 
 ---
 
@@ -709,8 +901,6 @@ MIT
 If you find **testflow-ai** useful, consider supporting its development:
 
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/carbajalmarcos)
-[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-ea4aaa?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/carbajalmarcos)
-[![Ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/carbajalmarcos)
 
 **Crypto donations:**
 

package/examples/auth-flow.yaml

@@ -0,0 +1,52 @@
+# Auth flow — Login, use token, access protected resource.
+
+name: Authentication Flow
+description: Login and access a protected endpoint using the returned token
+tags:
+  - auth
+  - smoke
+
+steps:
+  - name: Login
+    request:
+      method: POST
+      url: "{api}/auth/login"
+      headers:
+        Content-Type: application/json
+      body:
+        email: admin@example.com
+        password: secret
+    capture:
+      - name: token
+        path: data.accessToken
+      - name: userId
+        path: data.user.id
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.accessToken
+        operator: exists
+
+  - name: Access protected route
+    request:
+      method: GET
+      url: "{api}/users/${userId}"
+      headers:
+        Authorization: "Bearer ${token}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.id
+        operator: equals
+        value: "${userId}"
+
+  - name: Reject without token
+    request:
+      method: GET
+      url: "{api}/users/${userId}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 401

package/examples/context.md

@@ -0,0 +1,25 @@
+# My API
+
+## Description
+Example API context for testflow-ai.
+
+## Base URLs
+- api: http://localhost:3000
+- graphql: http://localhost:3000/graphql
+
+## Endpoints
+- POST /users - Create a new user
+- GET /users/:id - Get user by ID
+- PUT /users/:id - Update user
+- DELETE /users/:id - Delete user
+- POST /auth/login - Authenticate and get token
+- POST /graphql - GraphQL endpoint
+
+## Rules
+- All endpoints return JSON
+- Authentication required for /users endpoints
+- Rate limit: 100 requests per minute
+
+## AI Configuration
+- url: http://localhost:11434
+- model: llama3.2:3b

package/examples/graphql-flow.yaml

@@ -0,0 +1,58 @@
+# GraphQL — Mutation + query with variable capture.
+
+name: GraphQL User Flow
+description: Create a user via mutation, then query it back
+tags:
+  - graphql
+  - users
+
+steps:
+  - name: Create user (mutation)
+    request:
+      method: POST
+      url: "{graphql}"
+      graphql:
+        query: |
+          mutation CreateUser($input: CreateUserInput!) {
+            createUser(input: $input) {
+              id
+              email
+              name
+            }
+          }
+        variables:
+          input:
+            email: bob@example.com
+            name: Bob
+    capture:
+      - name: userId
+        path: data.createUser.id
+    assertions:
+      - path: data.createUser.email
+        operator: equals
+        value: bob@example.com
+      - path: data.createUser.id
+        operator: exists
+
+  - name: Query user
+    request:
+      method: POST
+      url: "{graphql}"
+      graphql:
+        query: |
+          query GetUser($id: ID!) {
+            user(id: $id) {
+              id
+              email
+              name
+            }
+          }
+        variables:
+          id: "${userId}"
+    assertions:
+      - path: data.user.id
+        operator: equals
+        value: "${userId}"
+      - path: data.user.email
+        operator: equals
+        value: bob@example.com

package/examples/rest-crud.yaml

@@ -0,0 +1,76 @@
+# REST CRUD — Create, read, update, verify a user.
+
+name: User CRUD
+description: Full lifecycle test for a REST user resource
+tags:
+  - users
+  - crud
+  - smoke
+
+steps:
+  - name: Create user
+    request:
+      method: POST
+      url: "{api}/users"
+      headers:
+        Content-Type: application/json
+      body:
+        email: alice@example.com
+        name: Alice
+    capture:
+      - name: userId
+        path: data.id
+      - name: userEmail
+        path: data.email
+    assertions:
+      - path: status
+        operator: equals
+        value: 201
+      - path: data.email
+        operator: equals
+        value: alice@example.com
+      - path: data.id
+        operator: exists
+
+  - name: Read user
+    request:
+      method: GET
+      url: "{api}/users/${userId}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.id
+        operator: equals
+        value: "${userId}"
+      - path: data.email
+        operator: equals
+        value: "${userEmail}"
+
+  - name: Update user
+    request:
+      method: PUT
+      url: "{api}/users/${userId}"
+      headers:
+        Content-Type: application/json
+      body:
+        name: Alice Updated
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.name
+        operator: equals
+        value: Alice Updated
+
+  - name: Verify update
+    request:
+      method: GET
+      url: "{api}/users/${userId}"
+    assertions:
+      - path: data.name
+        operator: equals
+        value: Alice Updated
+      - path: data.email
+        operator: equals
+        value: "${userEmail}"

package/examples/todo-crud.yaml

@@ -0,0 +1,97 @@
+# Todo List CRUD — Complete lifecycle test
+
+name: Todo CRUD Flow
+description: Create, read, update, and delete a todo item
+tags:
+  - todos
+  - crud
+  - smoke
+
+steps:
+  - name: Create todo
+    request:
+      method: POST
+      url: "{api}/todos"
+      headers:
+        Content-Type: application/json
+      body:
+        title: "Buy groceries"
+        completed: false
+    capture:
+      - name: todoId
+        path: data.id
+      - name: todoTitle
+        path: data.title
+    assertions:
+      - path: status
+        operator: equals
+        value: 201
+      - path: data.title
+        operator: equals
+        value: "Buy groceries"
+      - path: data.completed
+        operator: equals
+        value: false
+      - path: data.id
+        operator: exists
+
+  - name: Read todo
+    request:
+      method: GET
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.id
+        operator: equals
+        value: "${todoId}"
+      - path: data.title
+        operator: equals
+        value: "${todoTitle}"
+
+  - name: Update todo
+    request:
+      method: PUT
+      url: "{api}/todos/${todoId}"
+      headers:
+        Content-Type: application/json
+      body:
+        completed: true
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+      - path: data.completed
+        operator: equals
+        value: true
+
+  - name: Verify update
+    request:
+      method: GET
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: data.completed
+        operator: equals
+        value: true
+      - path: data.title
+        operator: equals
+        value: "${todoTitle}"
+
+  - name: Delete todo
+    request:
+      method: DELETE
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 200
+
+  - name: Verify deletion
+    request:
+      method: GET
+      url: "{api}/todos/${todoId}"
+    assertions:
+      - path: status
+        operator: equals
+        value: 404

package/examples/todo-graphql.yaml

@@ -0,0 +1,59 @@
+# GraphQL Todo Flow — Mutation + query with variable capture
+
+name: GraphQL Todo Flow
+description: Create a todo via mutation, then query it back
+tags:
+  - graphql
+  - todos
+
+steps:
+  - name: Create todo (mutation)
+    request:
+      method: POST
+      url: "{graphql}"
+      graphql:
+        query: |
+          mutation CreateTodo($input: CreateTodoInput!) {
+            createTodo(input: $input) {
+              id
+              title
+              completed
+              createdAt
+            }
+          }
+        variables:
+          input:
+            title: "Learn testflow-ai"
+            completed: false
+    capture:
+      - name: todoId
+        path: data.createTodo.id
+    assertions:
+      - path: data.createTodo.title
+        operator: equals
+        value: "Learn testflow-ai"
+      - path: data.createTodo.id
+        operator: exists
+
+  - name: Query todo
+    request:
+      method: POST
+      url: "{graphql}"
+      graphql:
+        query: |
+          query GetTodo($id: ID!) {
+            todo(id: $id) {
+              id
+              title
+              completed
+            }
+          }
+        variables:
+          id: "${todoId}"
+    assertions:
+      - path: data.todo.id
+        operator: equals
+        value: "${todoId}"
+      - path: data.todo.title
+        operator: equals
+        value: "Learn testflow-ai"

package/examples/todo-list-context.md

@@ -0,0 +1,27 @@
+# Todo List API
+
+## Description
+A simple REST API for managing todo items with authentication.
+
+## Base URLs
+- api: http://localhost:3000
+- graphql: http://localhost:3000/graphql
+
+## Endpoints
+- POST /todos - Create a new todo
+- GET /todos/:id - Get todo by ID
+- GET /todos - List all todos
+- PUT /todos/:id - Update todo
+- DELETE /todos/:id - Delete todo
+- POST /auth/login - Authenticate and get token
+- POST /graphql - GraphQL endpoint
+
+## Rules
+- All endpoints return JSON
+- Authentication required for /todos endpoints
+- Todos have: id, title, completed, createdAt
+
+## AI Configuration
+- provider: ollama
+- url: http://localhost:11434
+- model: llama3.2:3b

package/package.json

@@ -1,70 +1,71 @@
 {
-  "name": "testflow-ai",
-  "version": "0.3.0",
-  "description": "Declarative API testing powered by YAML flows. Replace Postman with version-controlled, AI-friendly test definitions.",
-  "author": "Marcos Carbajal",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/carbajalmarcos/testflow-ai"
-  },
-  "homepage": "https://github.com/carbajalmarcos/testflow-ai#readme",
-  "bugs": {
-    "url": "https://github.com/carbajalmarcos/testflow-ai/issues"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+    "name": "testflow-ai",
+    "version": "0.4.0",
+    "description": "Declarative API testing powered by YAML flows. Replace Postman with version-controlled, AI-friendly test definitions.",
+    "author": "Marcos Carbajal",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/carbajalmarcos/testflow-ai"
+    },
+    "homepage": "https://github.com/carbajalmarcos/testflow-ai#readme",
+    "bugs": {
+        "url": "https://github.com/carbajalmarcos/testflow-ai/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "bin": {
+        "testflow": "./dist/cli.js",
+        "tflow": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE",
+        "examples"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "tsc --noEmit",
+        "clean": "rm -rf dist",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "testing",
+        "api-testing",
+        "declarative",
+        "yaml",
+        "e2e",
+        "integration",
+        "graphql",
+        "rest",
+        "http",
+        "ai",
+        "ollama",
+        "flow",
+        "ci-cd",
+        "test-automation"
+    ],
+    "dependencies": {
+        "axios": "^1.7.0",
+        "commander": "^12.1.0",
+        "glob": "^11.0.0",
+        "yaml": "^2.4.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "^5.7.0",
+        "vitest": "^2.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
     }
-  },
-  "bin": {
-    "testflow": "./dist/cli.js",
-    "tflow": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "testing",
-    "api-testing",
-    "declarative",
-    "yaml",
-    "e2e",
-    "integration",
-    "graphql",
-    "rest",
-    "http",
-    "ai",
-    "ollama",
-    "flow",
-    "ci-cd",
-    "test-automation"
-  ],
-  "dependencies": {
-    "axios": "^1.7.0",
-    "commander": "^12.1.0",
-    "glob": "^11.0.0",
-    "yaml": "^2.4.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0",
-    "vitest": "^2.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
 }