analyzing-test-coverage

"Creates and analyzes tests using Vitest and MSW patterns. Generates test builders, mocks repositories, and configures integration tests. Tr
Open source Open in the app JSON README (API)
About

"Creates and analyzes tests using Vitest and MSW patterns. Generates test builders, mocks repositories, and configures integration tests. Triggers on: write tests, test coverage, Vitest, MSW mock, vi.
Details

Kind: Agent skills
Topic: No topic detected
Publisher: saleor
Origin: majiayu
Category: ferramentas
Stars: 20
Forks: 5
Open pull requests: 2
Last push: 2026-08-17T11:23:55Z
Repository state: ativo
Language: TypeScript
License: BSD-3-Clause
Added: 2026-09-01 17:06:52
Updated: 2026-09-01 17:06:52
Origin id: saleor/configurator/testing/analyzing-test-coverage@main
README

# Saleor Configurator

> Commerce as Code — Define your Saleor store in YAML, sync with your instance

[![npm version](https://img.shields.io/npm/v/@saleor/configurator.svg)](https://www.npmjs.com/package/@saleor/configurator)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Declarative configuration management for [Saleor](https://saleor.io) e-commerce stores.

## What is Saleor Configurator?

Saleor Configurator brings **infrastructure-as-code** principles to e-commerce. Instead of manually configuring your store through the dashboard, you define everything in version-controlled YAML files and sync them to your Saleor instance.

**Key Benefits:**

- **Version Control** — Track all store changes in Git with full history
- **Reproducibility** — Spin up identical configurations across environments
- **Multi-Environment** — Manage dev, staging, and production from the same codebase
- **Review Process** — Use pull requests to review configuration changes
- **Automation** — Integrate with CI/CD for automated deployments

```
┌─────────────┐     introspect     ┌─────────────┐
│   Saleor    │ ─────────────────► │  config.yml │
│  Instance   │                    │   (local)   │
└─────────────┘                    └─────────────┘
       ▲                                  │
       │                                  │
       │         deploy                   │ modify
       └──────────────────────────────────┘
```

## Quick Start

**Prerequisites:** Node.js 20+

### Compatibility

Configurator releases follow the supported Saleor major and minor version. Configurator `3.23.x` targets Saleor `3.23.x`.

The supported Saleor minor is declared in `package.json#saleor.schemaVersion`. Patch versions within that Saleor minor are treated as compatible. Older Saleor minors may still work, but they are not active support targets for the latest configurator line.

### Installation

```bash
# Run directly (recommended)
npx @saleor/configurator start
pnpm dlx @saleor/configurator start

# Or install globally
npm install -g @saleor/configurator
pnpm add -g @saleor/configurator
```

### Getting Your API Token

Before using Saleor Configurator, you need an API token from your Saleor instance. This token allows the CLI to read and modify your store configuration.

#### Step 1: Access Your Saleor Dashboard

Go to your Saleor Dashboard:
- **Saleor Cloud**: `https://your-store.saleor.cloud/dashboard/`
- **Self-hosted**: `https://your-domain.com/dashboard/`

#### Step 2: Create a New App

1. Navigate to **Extensions** → **Installed** in the sidebar
2. Click **Add Extension** → **Provide details manually**
3. Enter a name like `Configurator` or `Configuration Manager`

#### Step 3: Assign Permissions

Grant the app **all permissions** needed for configuration management:

| Permission Category | Required For |
|---------------------|--------------|
| **Products** | Product types, categories, products, variants |
| **Channels** | Sales channels, currency settings |
| **Shipping** | Shipping zones, methods, warehouses |
| **Pages** | Page types (model types), pages (models) |
| **Menus** | Navigation structures |
| **Discounts** | Vouchers and sales (if using) |
| **Settings** | Shop settings, tax configuration |

> **Tip:** For full configuration management, select all available permissions. You can restrict permissions later for specific environments.

#### Step 4: Generate the Token

1. After creating the app, go to the app's detail page
2. Find the **Tokens** section
3. Click **Create Token**
4. Copy the token immediately — it won't be shown again

Your token will look like: `eyJhbGciOiJSUzI1NiIsInR5cCI6...` (JWT format) or a shorter alphanumeric string.

#### Step 5: Store Your Credentials

For repeated use, store your credentials as environment variables:

```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export SALEOR_URL="https://your-store.saleor.cloud/graphql/"
export SALEOR_TOKEN="your-token-here"

# Then use in commands
npx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
```

> **Security Note:** Never commit tokens to version control. Use environment variables or a secrets manager.

#### Verify Your Setup

Test that your token works:

```bash
npx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN --include shop
```

If successful, you'll see your shop settings downloaded. If you get an authentication error, verify your token and URL (ensure the URL ends with `/graphql/`).

### First-Time Setup

The easiest way to get started is with the interactive wizard:

```bash
npx @saleor/configurator start
```

### Core Workflow

```bash
# 1. Download your current store configuration
npx @saleor/configurator introspect \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token

# 2. Modify config.yml to define your desired state

# 3. Preview changes before applying
npx @saleor/configurator diff \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token

# 4. Deploy your configuration
npx @saleor/configurator deploy \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token
```

> **Need a token?** See [Getting Your API Token](#getting-your-api-token) above for step-by-step instructions.

### Quick Reference

| Task | Command |
|------|---------|
| Download config | `npx @saleor/configurator introspect --url <URL> --token <TOKEN>` |
| Preview changes | `npx @saleor/configurator diff --url <URL> --token <TOKEN>` |
| Deploy changes | `npx @saleor/configurator deploy --url <URL> --token <TOKEN>` |
| Apply recipe | `npx @saleor/configurator recipe apply <name> --url <URL> --token <TOKEN>` |
| CI deployment | `npx @saleor/configurator deploy --url <URL> --token <TOKEN> --fail-on-delete` |

## Commands

All commands support `--help` for detailed usage information.

### `start` — Interactive Wizard

Guided setup for exploring features and connecting to your Saleor instance.

```bash
npx @saleor/configurator start
```

### `introspect` — Download Remote Config

Fetches the current configuration from your Saleor instance and saves it locally.

```bash
npx @saleor/configurator introspect --url <URL> --token <TOKEN>

# With custom output file
npx @saleor/configurator introspect --url <URL> --token <TOKEN> --config production.yml
```

### `diff` — Preview Changes

Shows what would change if you deployed, without making any modifications.

```bash
npx @saleor/configurator diff --url <URL> --token <TOKEN>
```

### `deploy` — Apply Configuration

Syncs your local configuration to the remote Saleor instance.

```bash
# Interactive mode with confirmation prompts
npx @saleor/configurator deploy --url <URL> --token <TOKEN>

# Custom config file
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --config production.yml
```

### `recipe` — Pre-Built Templates

Apply ready-to-use configuration templates for common e-commerce scenarios.

```bash
# List available recipes
npx @saleor/configurator recipe list

# Preview a recipe's configuration
npx @saleor/configurator recipe show multi-region

# Apply a recipe to your instance
npx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>

# Export for customization
npx @saleor/configurator recipe export multi-region --output my-config.yml
```

## Configuration

Define your store configuration in YAML (default: `config.yml`).

### Structure Overview

```yaml
# Global store settings
shop:
  defaultMailSenderName: "My Store"
  displayGrossPrices: true

# Sales channels (multi-currency, multi-region)
channels:
  - name: "United States"
    slug: us
    currencyCode: USD
    defaultCountry: US

# Product catalog structure
productTypes:
  - name: "Book"
    isShippingRequired: true
    productAttributes:
      - name: "Author"
        inputType: PLAIN_TEXT

categories:
  - name: "Fiction"
    slug: fiction
    subcategories:
      - name: "Fantasy"
        slug: fantasy

products:
  - name: "Sample Book"
    slug: sample-book
    productType: "Book"
    category: fiction
    variants:
      - name: "Hardcover"
        sku: "BOOK-001"

# Fulfillment
warehouses:
  - name: "Main Warehouse"
    slug: main-warehouse
    address:
      streetAddress1: "123 Commerce St"
      city: "New York"
      country: US

shippingZones:
  - name: "US Zone"
    countries: ["US"]
    warehouses: ["main-warehouse"]
```

### Domain Modeling

Saleor's domain model consists of interconnected entity types that you can configure declaratively.

#### Core Entities

| Entity | Purpose | Configured Via |
|--------|---------|----------------|
| **Products** | Sellable items with variants, pricing, stock | `products` |
| **Product Types** | Templates defining product structure and attributes | `productTypes` |
| **Categories** | Hierarchical product taxonomy (one category per product) | `categories` |
| **Collections** | Flexible product groupings for merchandising | `collections` |
| **Models** | Custom entities extending beyond products (e.g., Brands, Ingredients) | `models` |
| **Model Types** | Templates defining model structure | `pageTypes` |
| **Structures** | Hierarchical navigation linking categories, collections, models, URLs | `menus` |

#### Attributes

Attributes are reusable typed fields assigned to products or models:

| Type | Description | Example |
|------|-------------|---------|
| `DROPDOWN` | Single-select from predefined values | Color: Red, Blue, Green |
| `MULTISELECT` | Multi-select from predefined values | Tags: Sale, New, Featured |
| `PLAIN_TEXT` | Unformatted text | Material: "100% Cotton" |
| `RICH_TEXT` | Formatted content blocks | Product description |
| `NUMERIC` | Numbers with optional units | Weight: 500g |
| `BOOLEAN` | Yes/no values | Fair trade certified |
| `DATE` / `DATE_TIME` | Date values | Release date |
| `FILE` | File attachments | Product manual PDF |
| `SWATCH` | Color codes or images | Visual color picker |
| `REFERENCE` | Links to other entities | Related products |

#### Linking Entities with REFERENCE Attributes

Connect products to other products, models, or variants:

```yaml
productTypes:
  - name: "Perfume"
    productAttributes:
      - name: "Scent Profiles"
        inputType: REFERENCE
        entityType: PAGE          # Links to Models
      - name: "Related Products"
        inputType: REFERENCE
        entityType: PRODUCT       # Links to other Products
```

#### Custom Entities with Models

Extend your domain beyond products using Models (internally called Pages):

```yaml
# Define structure with pageTypes
pageTypes:
  - name: "Brand"
    attributes:
      - name: "Country"
        inputType: DROPDOWN
        values: [{ name: "France" }, { name: "Italy" }, { name: "USA" }]
      - name: "Founded"
        inputType: NUMERIC

# Create instances with models
models:
  - title: "Maison Lumière"
    slug: "maison-lumiere"
    modelType: "Brand"
    attributes:
      country: "France"
      founded: 1925
```

#### Structures (Navigation)

Organize entities hierarchically using menus:

```yaml
menus:
  - name: "Main Navigation"
    slug: "main-nav"
    items:
      - name: "Shop"
        category: "all-products"      # Link to Category
      - name: "Collections"
        children:
          - name: "Summer Sale"
            collection: "summer-sale" # Link to Collection
      - name: "Our Brands"
        page: "maison-lumiere"        # Link to Model
      - name: "Help"
        url: "https://help.example.com"  # External URL
```

**Learn more:** [Saleor Modeling](https://docs.saleor.io/developer/modeling) · [Attributes](https://docs.saleor.io/developer/attributes/overview) · [Products](https://docs.saleor.io/developer/products/overview)

### Entity Identification

Entities are identified by either `slug` or `name` depending on their type:

| Identifier | Entity Types |
|------------|--------------|
| **slug** | Channels, Categories, Collections, Menus, Pages, Products, Warehouses |
| **name** | ProductTypes, PageTypes, TaxClasses, ShippingZones, Attributes |

When referencing entities, use the appropriate identifier:

```yaml
products:
  - name: "Sample Book"
    productType: "Book"        # Reference by name (ProductType)
    category: "fiction"        # Reference by slug (Category)
    collections: ["featured"]  # Reference by slug (Collection)
```

### Complete Reference

- **[SCHEMA.md](SCHEMA.md)** — Full field documentation and validation rules
- **[example.yml](example.yml)** — Comprehensive working example

## Recipes

Recipes are pre-built YAML configuration templates for common e-commerce scenarios. They complement the [Saleor Recipes documentation](https://docs.saleor.io/recipes/overview) by providing ready-to-deploy configurations you can apply directly or customize.

### Available Recipes

| Recipe | Description | Entities |
|--------|-------------|----------|
| **multi-region** | US, EU, UK markets with regional warehouses | Channels, Warehouses, ShippingZones |
| **digital-products** | Product types for non-physical goods | ProductTypes |
| **click-and-collect** | Warehouse pickup points with local collection | Warehouses, ShippingZones |
| **custom-shipping** | Complex shipping zones and rate structures | ShippingZones |

### Quick Start with Recipes

```bash
# List all recipes with descriptions
npx @saleor/configurator recipe list

# Preview what a recipe contains
npx @saleor/configurator recipe show multi-region

# Apply directly to your instance
npx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>

# Export and customize before applying
npx @saleor/configurator recipe export multi-region --output my-store.yml
# Edit my-store.yml...
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --config my-store.yml
```

> **Note:** More recipes are planned. Check `recipe list` for the current catalog.

See [recipes/README.md](recipes/README.md) for detailed recipe documentation and customization guides.

## CI/CD Integration

Automate configuration deployments with GitHub Actions or other CI systems.

### GitHub Actions Example

```yaml
name: Deploy Saleor Configuration

on:
  push:
    branches: [main]
    paths: ['config.yml']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Preview changes
        run: |
          npx @saleor/configurator diff \
            --url ${{ secrets.SALEOR_URL }} \
            --token ${{ secrets.SALEOR_TOKEN }}

      - name: Deploy configuration
        run: |
          npx @saleor/configurator deploy \
            --url ${{ secrets.SALEOR_URL }} \
            --token ${{ secrets.SALEOR_TOKEN }} \
```

### Key Flags for Automation

| Flag | Description |
|------|-------------|
| `--json` | Output machine-readable JSON |
| `--fail-on-delete` | Exit code 6 if deletions detected |
| `--fail-on-breaking` | Exit code 7 if breaking changes detected |
| `--quiet` | Suppress non-essential output |

Non-interactive mode is auto-detected in non-TTY environments (pipes, CI, subprocesses).

### Multi-Environment Pattern

```bash
# Production deployment
npx @saleor/configurator deploy \
  --url $PROD_URL --token $PROD_TOKEN \
  --config config.yml --fail-on-delete

# Staging deployment
npx @saleor/configurator deploy \
  --url $STAGING_URL --token $STAGING_TOKEN \
  --config config.yml
```

See [docs/ci-cd/README.md](docs/ci-cd/README.md) for workflow templates, exit codes, and advanced patterns.

## Troubleshooting

### Common Issues

**Authentication Failed**
- Verify your token in the Saleor dashboard
- Ensure the app has all required permissions
- Check that the URL ends with `/graphql/`

**Entity Reference Errors**
- Verify referenced entities exist (e.g., categories before products)
- Check identifier types: use `slug` for categories, `name` for product types
- Run `diff` to see what's missing

**Validation Errors**
- Check required fields are present
- Validate enum values match the schema
- See [SCHEMA.md](SCHEMA.md) for field requirements

### Diagnostic Commands

```bash
# Test connectivity
npx @saleor/configurator introspect --url <URL> --token <TOKEN> --include shop

# Preview without changes (show plan only)
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --plan

# Debug mode
LOG_LEVEL=debug npx @saleor/configurator diff --url <URL> --token <TOKEN>
```

See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for detailed troubleshooting procedures.

## AI Agent Integration

Saleor Configurator provides first-class support for AI coding tools through two mechanisms:

### Portable Skills (`skills/`)

Nine portable skills usable by any AI coding tool (Codex, Cursor, Copilot, Gemini CLI, etc.):

```bash
# Install via skills.sh
npx skills add saleor/configurator
```

Skills cover CLI usage, config schema, Saleor domain modeling, product design, recipes, data import, output parsing, deployment workflows, and troubleshooting.

### Claude Code Plugin (`plugin/`)

Full-featured Claude Code plugin with slash commands, autonomous agents, hooks, and MCP integrations:

```bash
claude --plugin-dir ./plugin
```

See [`AGENTS.md`](AGENTS.md) for the complete AI agent integration guide.

## Contributing

### Development Setup

```bash
# Clone and install
git clone https://github.com/saleor/configurator.git
cd configurator
pnpm install

# Run in development mode
pnpm dev start
pnpm dev introspect --url <URL> --token <TOKEN>

# Build and test
pnpm build
pnpm test
```

### Quality Standards

```bash
# Before committing
pnpm check:fix && pnpm build && pnpm test
```

### Versioning

This project uses [Changesets](https://github.com/changesets/changesets) for release notes and publishing, with one repository-specific rule: configurator package major and minor versions follow the supported Saleor major and minor.

```bash
# Document your changes
pnpm changeset
```

Release rules:

- Patch fixes for the current Saleor target use a patch changeset.
- Moving support to the next Saleor minor updates `package.json#saleor.schemaVersion` and uses a minor changeset.
- The first Saleor-bound release from `1.x` to `3.23.0` requires manually editing the generated release PR version.
- Releases are published from `main` by the GitHub Actions release workflow.

For example, configurator `3.23.x` targets Saleor `3.23.x`; configurator `3.24.0` starts the Saleor `3.24.x` line.

See [docs/DEVELOPMENT_WORKFLOWS.md](docs/DEVELOPMENT_WORKFLOWS.md) for detailed contribution guidelines.

## Documentation

| Document | Description |
|----------|-------------|
| [SCHEMA.md](SCHEMA.md) | Complete configuration field reference |
| [example.yml](example.yml) | Working example with all entity types |
| [recipes/README.md](recipes/README.md) | Pre-built recipe templates |
| [docs/COMMANDS.md](docs/COMMANDS.md) | Complete CLI reference |
| [docs/ci-cd/README.md](docs/ci-cd/README.md) | CI/CD integration guide |
| [docs/ENTITY_REFERENCE.md](docs/ENTITY_REFERENCE.md) | Entity types and identification |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Problem diagnosis and fixes |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design and internals |
| [docs/DEVELOPMENT_WORKFLOWS.md](docs/DEVELOPMENT_WORKFLOWS.md) | Contributor guide |
| [docs/CODE_QUALITY.md](docs/CODE_QUALITY.md) | Coding standards |
| [docs/TESTING_PROTOCOLS.md](docs/TESTING_PROTOCOLS.md) | Testing guidelines |

## License

MIT License - see [LICENSE](LICENSE) for details.