Sanity Testing

What it is

A sanity test is a narrow, focused check that a specific change or bug fix works as intended. It is the opposite shape to smoke: deep but not wide. You do not sweep the whole system — you confirm one area behaves after a change, before investing in a fuller test pass.

1
  change ──► SANITY (one area, deep) ──► regression / full suite
2
               │ pass                        │
3
               └ fail → fix, do not proceed  └ wider safety net

A useful contrast: smoke is a shallow sweep of the whole build; sanity is a deep look at one slice. Smoke says “the build is alive”; sanity says “this fix actually fixed it”.

When to use it / when to avoid it

Use it for

Right after a bug fix or a small change, before running the full suite
Confirming a specific feature you just touched still behaves
A quick accept/reject gate on a candidate build for one area

Avoid it when

You need to know the whole build is stable → use smoke testing
You need to prove the change did not break anything else → follow with a regression test
The change is broad or architectural — sanity’s narrow scope will miss knock-on effects

Frameworks & tools

Tool	Ecosystem	Notes
Vitest / Jest	JS/TS	Run a single file: `vitest run path/to/feature`
Playwright	Multi	`--grep` a feature by tag or title
pytest	Python	`pytest tests/test_feature.py -k "checkout"`
Go testing	Go	`go test ./pkg/checkout/...`
JUnit 5	Java/JVM	Run one class or `@Tag` via Surefire
xUnit / NUnit	.NET	`dotnet test --filter FullyQualifiedName~Checkout`
Robot Framework	Python	Select a tag: `robot --include sanity tests/`
Postman / Newman	Multi	Replay the affected requests only

Quick setup

1
npx vitest run src/checkout/checkout.test.ts
2
# or a tagged slice
3
npx playwright test --grep @sanity

1
pytest tests/test_checkout.py -k "discount" -q

1
go test ./pkg/checkout/... -run TestDiscount -count=1

1
<!-- Maven: run a single folder of sanity tests -->
2
<configuration>
3
  <includes>
4
    <include>**/sanity/*Test.java</include>
5
  </includes>
6
</configuration>

1
dotnet test --filter "FullyQualifiedName~CheckoutTests"

Example

1
import { describe, it, expect } from 'vitest';
2
import { applyCoupon } from './apply-coupon';
3

4
describe('applyCoupon (sanity after the fix)', () => {
5
  it('rejects an expired coupon', () => {
6
    const result = applyCoupon('EXPIRED10', { expires: '2020-01-01' });
7
    expect(result.error).toBe('coupon_expired');
8
  });
9
});

1
from apply_coupon import apply_coupon
2

3
def test_rejects_expired_coupon():
4
    result = apply_coupon("EXPIRED10", expires="2020-01-01")
5
    assert result["error"] == "coupon_expired"

1
func TestSanityRejectsExpiredCoupon(t *testing.T) {
2
  res := ApplyCoupon("EXPIRED10", "2020-01-01")
3
  if res.Error != "coupon_expired" {
4
    t.Fatalf("want coupon_expired, got %q", res.Error)
5
  }
6
}

1
import static org.junit.jupiter.api.Assertions.assertEquals;
2
import org.junit.jupiter.api.Test;
3

4
class CouponSanityTest {
5
  @Test
6
  void rejectsExpiredCoupon() {
7
    var result = Coupon.apply("EXPIRED10", "2020-01-01");
8
    assertEquals("coupon_expired", result.error());
9
  }
10
}

1
using Xunit;
2

3
public class CouponSanityTests
4
{
5
    [Fact]
6
    public void RejectsExpiredCoupon()
7
    {
8
        var result = Coupon.Apply("EXPIRED10", "2020-01-01");
9
        Assert.Equal("coupon_expired", result.Error);
10
    }
11
}

Anti-patterns & best practices

Keep it narrow. One change, one area; if it is sweeping the whole system, it is smoke.
Pick the assert that proves the fix. Target the exact behaviour the bug broke.
Do not stop at sanity. Sanity confirms the fix; a regression pass confirms nothing else broke.
Reuse existing tests. Prefer selecting a slice of the suite over writing throwaway code.
Time-box it. Sanity should be minutes; long sessions mean you are doing regression.
Make the target explicit. Tag or filter so “run sanity” is one deterministic command.