Documentation
¶
Index ¶
- Constants
- Variables
- func AssertCommandFails(t *testing.T, logger *TestLogger, cmd string, args ...string) []byte
- func AssertCommandSuccess(t *testing.T, logger *TestLogger, cmd string, args ...string) []byte
- func AssertEventually(t *testing.T, logger *TestLogger, timeout time.Duration, ...) bool
- func AssertJSONField(t *testing.T, logger *TestLogger, output []byte, field string, ...)
- func AssertJSONOutput(t *testing.T, logger *TestLogger, output []byte)
- func AssertNTMStatus(t *testing.T, logger *TestLogger, sessionName string, expectedPanes int)
- func AssertPaneContains(t *testing.T, logger *TestLogger, name string, paneIndex int, substring string)
- func AssertPaneCount(t *testing.T, logger *TestLogger, name string, expected int)
- func AssertPaneCountAtLeast(t *testing.T, logger *TestLogger, name string, minimum int)
- func AssertSessionExists(t *testing.T, logger *TestLogger, name string)
- func AssertSessionNotExists(t *testing.T, logger *TestLogger, name string)
- func BuildLocalNTM(t *testing.T) string
- func CapturePane(name string, paneIndex int) (string, error)
- func CreateNTMConfig(t *testing.T, projectDir string, logger *TestLogger) string
- func CreateTestSession(t *testing.T, logger *TestLogger, config SessionConfig) string
- func CreateTestSessionSimple(t *testing.T, logger *TestLogger, agents map[string]int) string
- func E2ETestPrecheck(t *testing.T)
- func E2ETestPrecheckThrottled(t *testing.T)
- func GetSessionPaneCount(name string) (int, error)
- func IntegrationTestPrecheck(t *testing.T)
- func IntegrationTestPrecheckThrottled(t *testing.T)
- func KillAllTestSessions(logger *TestLogger)
- func KillAllTestSessionsSilent() int
- func RequireCI(t *testing.T)
- func RequireE2E(t *testing.T)
- func RequireEnv(t *testing.T, envVar string)
- func RequireIntegration(t *testing.T)
- func RequireLinux(t *testing.T)
- func RequireMacOS(t *testing.T)
- func RequireNTMBinary(t *testing.T)
- func RequireNotCI(t *testing.T)
- func RequireRoot(t *testing.T)
- func RequireTmux(t *testing.T)
- func RequireTmuxServer(t *testing.T)
- func RequireTmuxThrottled(t *testing.T)
- func RequireUnix(t *testing.T)
- func SessionExists(name string) bool
- func SkipIfBdUnavailable(t *testing.T)
- func SkipIfBvUnavailable(t *testing.T)
- func SkipIfCPUOverloaded(t *testing.T)
- func SkipIfMailUnavailable(t *testing.T)
- func SkipIfUBSUnavailable(t *testing.T)
- func SkipShort(t *testing.T)
- func WaitForSession(name string, timeout time.Duration) error
- type AgentConfig
- type SessionConfig
- type TestLogger
- func (l *TestLogger) Elapsed() time.Duration
- func (l *TestLogger) Exec(cmd string, args ...string) ([]byte, error)
- func (l *TestLogger) ExecContext(timeout time.Duration, cmd string, args ...string) ([]byte, error)
- func (l *TestLogger) Log(format string, args ...interface{})
- func (l *TestLogger) LogSection(name string)
Constants ¶
const CPUOverloadThreshold = 95.0
CPUOverloadThreshold is the percentage above which a core is considered overloaded.
Variables ¶
var TmuxTestThrottle = newThrottle(getTmuxTestLimit())
TmuxTestThrottle limits concurrent tmux session spawning in tests. This prevents fork bombs when running tests with high parallelism.
The default limit is 8 concurrent tmux-spawning tests, which is safe even on systems with lower process limits. Override with NTM_TEST_PARALLEL.
Functions ¶
func AssertCommandFails ¶
AssertCommandFails runs a command and verifies it fails (non-zero exit).
func AssertCommandSuccess ¶
AssertCommandSuccess runs a command and verifies it succeeds (exit 0).
func AssertEventually ¶
func AssertEventually(t *testing.T, logger *TestLogger, timeout time.Duration, interval time.Duration, description string, assertion func() bool) bool
AssertEventually retries an assertion until it passes or timeout. Returns true if the assertion passed, false if it timed out.
func AssertJSONField ¶
func AssertJSONField(t *testing.T, logger *TestLogger, output []byte, field string, expected interface{})
AssertJSONField verifies a field in JSON output has the expected value.
func AssertJSONOutput ¶
func AssertJSONOutput(t *testing.T, logger *TestLogger, output []byte)
AssertJSONOutput verifies that command output is valid JSON.
func AssertNTMStatus ¶
func AssertNTMStatus(t *testing.T, logger *TestLogger, sessionName string, expectedPanes int)
AssertNTMStatus verifies ntm status output for a session.
func AssertPaneContains ¶
func AssertPaneContains(t *testing.T, logger *TestLogger, name string, paneIndex int, substring string)
AssertPaneContains verifies that a pane's content contains a substring.
func AssertPaneCount ¶
func AssertPaneCount(t *testing.T, logger *TestLogger, name string, expected int)
AssertPaneCount verifies the number of panes in a session.
func AssertPaneCountAtLeast ¶
func AssertPaneCountAtLeast(t *testing.T, logger *TestLogger, name string, minimum int)
AssertPaneCountAtLeast verifies the session has at least N panes.
func AssertSessionExists ¶
func AssertSessionExists(t *testing.T, logger *TestLogger, name string)
AssertSessionExists verifies that a tmux session exists.
func AssertSessionNotExists ¶
func AssertSessionNotExists(t *testing.T, logger *TestLogger, name string)
AssertSessionNotExists verifies that a tmux session does not exist.
func BuildLocalNTM ¶
BuildLocalNTM builds the ntm binary from the current workspace and returns its path. It builds only once per test process.
func CapturePane ¶
CapturePane captures the visible content of a pane.
func CreateNTMConfig ¶
func CreateNTMConfig(t *testing.T, projectDir string, logger *TestLogger) string
CreateNTMConfig creates a temporary NTM config file pointing to the given project directory.
func CreateTestSession ¶
func CreateTestSession(t *testing.T, logger *TestLogger, config SessionConfig) string
CreateTestSession creates a new ntm session for testing. It automatically registers cleanup to kill the session when the test completes. Returns the session name.
Note: ntm spawn derives the project directory from NTM_PROJECTS_BASE + session name. This function sets NTM_PROJECTS_BASE to a temp directory and creates the project directory within it, named after the session.
func CreateTestSessionSimple ¶
CreateTestSessionSimple creates a session with a simple agent configuration. This is a convenience wrapper around CreateTestSession.
func E2ETestPrecheck ¶
E2ETestPrecheck runs all common prechecks for E2E tests.
func E2ETestPrecheckThrottled ¶
E2ETestPrecheckThrottled runs E2E prechecks with throttling. Use this instead of E2ETestPrecheck for tests that spawn tmux.
func GetSessionPaneCount ¶
GetSessionPaneCount returns the number of panes in a session.
func IntegrationTestPrecheck ¶
IntegrationTestPrecheck runs all common prechecks for integration tests. This is a convenience function that combines common skip conditions.
func IntegrationTestPrecheckThrottled ¶
IntegrationTestPrecheckThrottled runs integration prechecks with throttling. Use this instead of IntegrationTestPrecheck for tests that spawn tmux.
func KillAllTestSessions ¶
func KillAllTestSessions(logger *TestLogger)
KillAllTestSessions kills all ntm test sessions. Matches both naming conventions: "ntm_test_*" (underscore) and "ntm-test-*" (hyphen). Useful for cleanup in TestMain or after failed tests.
func KillAllTestSessionsSilent ¶
func KillAllTestSessionsSilent() int
KillAllTestSessionsSilent kills all ntm test sessions without logging. Use this in TestMain where a logger may not be available.
func RequireE2E ¶
RequireE2E skips the test unless E2E tests are enabled. Set NTM_E2E_TESTS=1 to run E2E tests.
func RequireEnv ¶
RequireEnv skips the test if the specified environment variable is not set.
func RequireIntegration ¶
RequireIntegration skips the test unless integration tests are enabled. Set NTM_INTEGRATION_TESTS=1 to run integration tests.
func RequireLinux ¶
RequireLinux skips the test on non-Linux systems.
func RequireMacOS ¶
RequireMacOS skips the test on non-macOS systems.
func RequireNTMBinary ¶
RequireNTMBinary ensures tests run against a repo-built ntm binary.
Many integration/E2E tests invoke "ntm" via PATH; relying on a globally installed binary is fragile (it may not match the workspace source). This helper builds the local binary once per test process and prepends it to PATH so LookPath/exec resolve the correct version.
func RequireNotCI ¶
RequireNotCI skips the test when running in CI environments. Useful for tests that require interactive terminal features.
func RequireRoot ¶
RequireRoot skips the test if not running as root.
func RequireTmux ¶
RequireTmux skips the test if tmux is not installed.
func RequireTmuxServer ¶
RequireTmuxServer skips the test if no tmux server is running. Some tests need a tmux server already running.
func RequireTmuxThrottled ¶
RequireTmuxThrottled combines RequireTmux with throttle acquisition. Use this at the start of any test that spawns tmux sessions.
Example:
func TestSpawnSession(t *testing.T) {
testutil.RequireTmuxThrottled(t)
// ... test code that spawns tmux sessions
}
func RequireUnix ¶
RequireUnix skips the test on non-Unix systems (Windows).
func SessionExists ¶
SessionExists checks if a tmux session exists.
func SkipIfBdUnavailable ¶
SkipIfBdUnavailable skips the test if bd (beads_rust) is not installed.
func SkipIfBvUnavailable ¶
SkipIfBvUnavailable skips the test if bv is not installed.
func SkipIfCPUOverloaded ¶
SkipIfCPUOverloaded checks if all CPU cores are at 95%+ utilization and skips the test if so. This prevents flaky timing-based benchmark tests when the system is under extreme load.
Use this at the start of any test that asserts on wall-clock time.
func SkipIfMailUnavailable ¶
SkipIfMailUnavailable skips the test if Agent Mail MCP server is not available.
func SkipIfUBSUnavailable ¶
SkipIfUBSUnavailable skips the test if UBS scanner is not installed.
Types ¶
type AgentConfig ¶
type AgentConfig struct {
Claude int // Number of Claude Code agents
Codex int // Number of Codex agents
Gemini int // Number of Gemini agents
}
AgentConfig specifies the number of agents of each type to spawn.
type SessionConfig ¶
type SessionConfig struct {
Agents AgentConfig
WorkDir string // Working directory for the session (used as NTM_PROJECTS_BASE)
ExtraArgs []string // Additional arguments to pass to ntm spawn
}
SessionConfig holds configuration for creating a test session.
type TestLogger ¶
type TestLogger struct {
// contains filtered or unexported fields
}
TestLogger provides structured logging for integration tests. It writes timestamped log entries to both a file and the test output.
func NewTestLogger ¶
func NewTestLogger(t *testing.T, logDir string) *TestLogger
NewTestLogger creates a new test logger that writes to both a log file and test output. The log file is created in logDir with a name based on the test name and timestamp. The file is automatically closed when the test completes via t.Cleanup.
func NewTestLoggerStdout ¶
func NewTestLoggerStdout(t *testing.T) *TestLogger
NewTestLoggerStdout creates a logger that only writes to test output (no file). Useful for simple tests that don't need persistent logs.
func (*TestLogger) Elapsed ¶
func (l *TestLogger) Elapsed() time.Duration
Elapsed returns the time elapsed since the test started.
func (*TestLogger) Exec ¶
func (l *TestLogger) Exec(cmd string, args ...string) ([]byte, error)
Exec runs a command and logs its execution, output, and exit status. Returns the combined stdout/stderr output and any error.
func (*TestLogger) ExecContext ¶
ExecContext runs a command with a timeout.
func (*TestLogger) Log ¶
func (l *TestLogger) Log(format string, args ...interface{})
Log writes a timestamped log entry.
func (*TestLogger) LogSection ¶
func (l *TestLogger) LogSection(name string)
LogSection writes a section header for grouping related log entries.
Source Files