OpenParable
Skip to content
← Back to skills

Tracee Testing Guide

Testing & Quality
tracee-testing-guide

Tracee Testing Guide is an Agent Skill for testing & quality published in the aquasecurity/tracee repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run Tracee tests correctly, especially BPF unit tests via make targets. Use when writing tests, debugging test failures, or validating changes before commit.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/aquasecurity/tracee/blob/HEAD/.cursor/skills/tracee-testing-guide/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tracee-testing-guide, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Tracee Testing Guide

Critical Rule

For BPF-related unit tests, do not run go test directly. Use make test-unit so the required BPF environment is configured.

When To Use This Skill

Use this skill when:

  • creating new unit tests for changed behavior
  • revising existing *_test.go files after refactors
  • fixing flaky tests or false assumptions in assertions
  • tightening coverage for bug fixes

Fast Development Commands

  • All unit tests: make test-unit
  • Package-only: make test-unit PKG=pkg/detectors
  • Function-only: make test-unit TEST=TestKernelVersionRequirement_Basic
  • Function in package: make test-unit PKG=pkg/ebpf/probes TEST=TestProbeCompatibility_Basic

Other Test Suites

  • Integration tests: make test-integration (root required)
  • E2E tests: make test-e2e, make test-e2e-net, make test-e2e-kernel (root required)
  • Coverage: make coverage, make coverage-html

Troubleshooting

  • fatal error: bpf/bpf.h: No such file or directory
    • Use make test-unit instead of direct go test.
  • Slow runs
    • Use PKG= and TEST= during iteration.
  • Integration or E2E failures
    • Verify root privileges and kernel eBPF support.

Test Authoring Notes

  • Use testify/assert and testify/require.
  • Keep test files near source (*_test.go).
  • Prefer explicit cleanup with defer.
  • Maintain or improve coverage for changed code.

Unit Test Creation Workflow

  1. Identify the behavior contract and edge cases from changed code.
  2. Add focused test cases first for success path, then error path.
  3. Use table-driven tests when only inputs/expected outputs vary.
  4. Keep each test name descriptive and behavior-based.
  5. Run targeted command first:
    • make test-unit PKG=<pkg> TEST=<TestName>
  6. Run package-wide tests:
    • make test-unit PKG=<pkg>
  7. Before finishing, run broader validation:
    • make test-unit

Unit Test Revision Workflow

When updating existing tests:

  • prefer fixing test intent instead of copying implementation details
  • remove stale assertions tied to old behavior
  • keep failure messages explicit so regressions are easy to diagnose
  • check cleanup paths and goroutine/resource lifecycle assumptions

Flaky Test Triage Checklist

  • verify timing assumptions (timeouts, retries, async ordering)
  • avoid shared mutable global state across tests
  • isolate test inputs from environment-dependent behavior
  • run the test repeatedly with:
    • make test-unit PKG=<pkg> TEST=<TestName>

Additional Reference

For a concise checklist to apply during unit test creation and review, see unit-test-checklist.md.