How DeskcommCRM SPECS_PARTE Lists Gate New Playwright Specs in CI

The 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 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, 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.

• 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:

# .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:

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 parses the YAML workflow file and enforces three critical invariants that prevent configuration drift:

1. Completeness: Every .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, 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:

// 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 to include the file in the desired partition. Choose the part that avoids resource conflicts (e.g., WAHA/Redis/Resend dependencies):

# .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:

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

The test will parse the updated YAML and confirm that 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:

# .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:

# 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 serve as the definitive whitelist for Playwright execution in CI.
• Zero silent skips: The e2e-cobertura-completa.test.ts unit test guarantees that every .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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}