# How DeskcommCRM SPECS_PARTE Lists Gate New Playwright Specs in CI

> Learn how DeskcommCRM SPECS_PARTE lists gate new Playwright specs in CI. Understand the e2e.yml workflow and spec whitelisting for efficient testing.

- Repository: [Rafael Melgaço/DeskcommCRM](https://github.com/melgarafael/DeskcommCRM)
- Tags: how-to-guide
- Published: 2026-09-13

---

**The [`e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/e2e.yml) workflow in `melgarafael/DeskcommCRM` uses three environment variables—`SPECS_PARTE_1`, `SPECS_PARTE_2`, and `SPECS_PARTE_3`—to explicitly whitelist which Playwright specs run in CI, while a unit test enforces that every [`.spec.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/.spec.ts) file on disk is either assigned to exactly one list or explicitly excluded.**

The `melgarafael/DeskcommCRM` repository employs a strict gating mechanism to manage its Playwright end-to-end test suite. By dividing tests across three parallel matrix jobs defined in [`.github/workflows/e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/.github/workflows/e2e.yml), the project prevents silent coverage gaps and ensures that no new spec file enters the codebase without explicit CI assignment. This article breaks down how the **`SPECS_PARTE_*` lists** function as the single source of truth for test execution and how automated validation prevents regressions.

## The Three-Part Matrix Strategy

The CI workflow splits the Playwright suite into three parallel execution groups to balance runtime and avoid IP rate limits. Each group is controlled by a dedicated environment variable defined in [`.github/workflows/e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/.github/workflows/e2e.yml).

- **`SPECS_PARTE_1`**: First third of the e2e suite
- **`SPECS_PARTE_2`**: Second third of the e2e suite  
- **`SPECS_PARTE_3`**: Final third of the e2e suite

The workflow passes these variables to Playwright via the `$LISTA` environment variable:

```yaml

# .github/workflows/e2e.yml

strategy:
  matrix:
    parte: [1, 2, 3]
env:
  SPECS_PARTE_1: >-
    login.spec.ts
    dashboard.spec.ts
  SPECS_PARTE_2: >-
    onboarding.spec.ts
    billing.spec.ts
  SPECS_PARTE_3: >-
    reports.spec.ts
    admin.spec.ts

```

During execution, the matrix job selects the appropriate list and invokes Playwright:

```bash
playwright test --workers=1 $LISTA

```

This parallelization keeps individual jobs under the 30-minute timeout while maximizing throughput across the GitHub Actions runner matrix.

## The Unit Test Gatekeeper

A dedicated unit test at [`tests/unit/e2e-cobertura-completa.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/e2e-cobertura-completa.test.ts) parses the YAML workflow file and enforces three critical invariants that prevent configuration drift:

1. **Completeness**: Every [`.spec.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/.spec.ts) file on disk must appear in exactly one `SPECS_PARTE_*` list, or alternatively in `FORA_DO_CI` with a documented reason.
2. **Currency**: No list may reference a file that has been deleted or renamed.
3. **Consumption**: The workflow must actually pass the list variables to Playwright via the `LISTA` substitution.

If a developer creates a new spec but forgets to update [`e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/e2e.yml), the unit test fails with a descriptive error:

```

Spec no disco que não roda no CI nem está declarada como fora…

```

This failure blocks the pull request, forcing explicit classification of the new test before it can merge.

## Adding a New Spec to the CI Pipeline

When introducing a new Playwright test, you must manually append the filename to the appropriate `SPECS_PARTE_*` variable based on execution time and dependency requirements. The process requires editing the workflow file directly.

First, create the spec file:

```typescript
// tests/e2e/nova-funcionalidade.spec.ts
import { test, expect } from '@playwright/test';

test('validates new feature', async ({ page }) => {
  await page.goto('/new-feature');
  await expect(page.locator('h1')).toContainText('New Feature');
});

```

Next, update [`.github/workflows/e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/.github/workflows/e2e.yml) to include the file in the desired partition. Choose the part that avoids resource conflicts (e.g., WAHA/Redis/Resend dependencies):

```yaml

# .github/workflows/e2e.yml

env:
  SPECS_PARTE_2: >-
    onboarding.spec.ts
    billing.spec.ts
    nova-funcionalidade.spec.ts   # ← new entry

```

Finally, run the unit test locally to validate your change before pushing:

```bash
pnpm test tests/unit/e2e-cobertura-completa.test.ts

```

The test will parse the updated YAML and confirm that [`nova-funcionalidade.spec.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/nova-funcionalidade.spec.ts) is accounted for and not duplicated across lists.

## Handling Exceptions with FORA_DO_CI

Not every Playwright spec can run in the standard CI environment due to external dependencies or infrastructure requirements. The workflow provides a **`FORA_DO_CI`** variable for explicit exclusion.

Add the spec name to `FORA_DO_CI` with a comment explaining the constraint:

```yaml

# .github/workflows/e2e.yml

env:
  FORA_DO_CI: >-
    vps-fresh-onboarding.spec.ts   # reason: depends on WAHA/Redis/Resend

    external-api-smoke.spec.ts     # reason: requires production API keys

```

The unit test permits these files to exist on disk without being present in the execution matrices, satisfying the completeness invariant while documenting why the test is skipped.

## Running Specs Locally for Debugging

To replicate the CI behavior locally, export the specific `SPECS_PARTE_*` variable as `LISTA` before invoking Playwright:

```bash

# Run the same subset as CI Part 1

LISTA="$SPECS_PARTE_1" pnpm exec playwright test --workers=1 $LISTA

```

This ensures your local execution matches the remote CI partition, including worker constraints and test isolation settings.

## Summary

- **Explicit gating**: The `SPECS_PARTE_*` environment variables in [`.github/workflows/e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/.github/workflows/e2e.yml) serve as the definitive whitelist for Playwright execution in CI.
- **Zero silent skips**: The [`e2e-cobertura-completa.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/e2e-cobertura-completa.test.ts) unit test guarantees that every [`.spec.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/.spec.ts) file is either assigned to a matrix part or explicitly marked in `FORA_DO_CI`.
- **Parallel safety**: Splitting the suite across three matrix jobs prevents IP rate limiting and respects GitHub Actions' 30-minute timeout.
- **Developer workflow**: Adding a new spec requires manual editing of [`e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/e2e.yml) and validation via the coverage unit test.

## Frequently Asked Questions

### What happens if I forget to add a new spec to the SPECS_PARTE lists?

The unit test [`tests/unit/e2e-cobertura-completa.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/e2e-cobertura-completa.test.ts) will fail during CI with the message "Spec no disco que não roda no CI nem está declarada como fora…", blocking your pull request until you add the file to the appropriate `SPECS_PARTE_*` variable or `FORA_DO_CI`.

### Can I move a spec from one SPECS_PARTE list to another?

Yes. Simply cut the filename from one `SPECS_PARTE_*` variable and paste it into another. The unit test will validate that the file appears exactly once across all three lists and is not duplicated or orphaned.

### How do I exclude a flaky or infrastructure-dependent test from CI?

Add the spec name to the `FORA_DO_CI` environment variable in [`.github/workflows/e2e.yml`](https://github.com/melgarafael/DeskcommCRM/blob/main/.github/workflows/e2e.yml) with a comment explaining the dependency (e.g., external APIs, Redis, or WAHA). This satisfies the coverage gate while preventing execution in the standard matrix.

### Why split the suite into three parts instead of running all tests in one job?

The three-part matrix prevents IP rate-limiting issues and ensures each parallel job completes within the 30-minute GitHub Actions timeout. Balancing execution time across `SPECS_PARTE_1`, `SPECS_PARTE_2`, and `SPECS_PARTE_3` allows the full suite to complete faster through parallelism than a single sequential run.