# Filtering

Run a subset of a Ginkgo suite, Pending/PIt/XIt, runtime Skip, programmatic Focus/FIt...

- Repository: https://github.com/onsi/ginkgo (9071 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add onsi/ginkgo --skill filtering -g -a claude-code -y`
Codex: `npx skills add onsi/ginkgo --skill filtering -g -a codex -y`
Cursor: `npx skills add onsi/ginkgo --skill filtering -g -a cursor -y`
Gemini CLI: `npx skills add onsi/ginkgo --skill filtering -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add onsi/ginkgo`

## Description

Run a subset of a Ginkgo suite, Pending/PIt/XIt, runtime Skip, programmatic Focus/FIt (and ginkgo unfocus), Label with the --label-filter query language and label sets, suite-level labels, SemVerConstraint/--sem-ver-filter, --focus/--skip and --focus-file/--skip-file, the filtering precedence rules, and --fail-on-pending/--fail-on-empty. Use when you want to run, skip, focus, label, or version-gate specs, or debug why specs were or weren't selected.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Filtering specs: running a subset

Ginkgo offers many ways to run fewer specs, ad-hoc (`Pending`/`Skip`/`Focus`) and structured (labels, semver, file/description filters). They combine by a strict precedence (see bottom). Decorator specifics live in `ginkgo:decorators`; label-driven CI in `ginkgo:ci`. Docs: <https://onsi.github.io/ginkgo/#filtering-specs>.

## Pending, compile-time skip, uncoercible

Marks a spec/container as under development. **Nothing can override `Pending` and make it run**, not focus, not labels.

```go
It("needs work", Pending, func() { ... })
It("placeholder", Pending)            // pending specs need no closure
PDescribe("not ready", func() { ... }) // == Describe(..., Pending); X-prefix is identical
PIt(...) / XIt(...) / PEntry(...)
```

Pending specs don't fail the suite. `ginkgo --fail-on-pending` makes them fail CI, a policy that pending specs shouldn't be committed. **Pending is compile-time only**; you cannot make a spec pending at runtime, for that, use `Skip`.

## Skip, runtime skip

Call `Skip("reason")` from any subject or setup node to skip during the run phase. It panics to halt the spec (like `Fail`) and records the reason; it **does not fail the suite** (even skipping every spec passes).

```go
It("if it can", func() {
	if !someCondition { Skip("special condition wasn't met") }
	...
})
```

Scope matters: in a `BeforeEach` it skips the current spec; in a `BeforeAll` it skips **all** specs in the `Ordered` container; in a `BeforeSuite` it skips the **entire suite**. **You cannot call `Skip` in a container body**, it only applies during the run phase.

## Focus, programmatic, for iterating (don't commit it)

When any spec is focused, Ginkgo runs **only** focused specs.

```go
FIt("just me", func() { ... })   // or It(..., Focus, ...)
FDescribe(...) / FContext(...) / FEntry(...)
```

The rest: https://github.com/onsi/ginkgo/blob/HEAD/plugins/ginkgo/skills/filtering/SKILL.md