storetest

package
v0.5.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 8, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package storetest provides a shared, engine-agnostic behavioral contract suite for the core subtitle store. It depends ONLY on internal/subflux, so it pins behaviour at the store's own contract rather than at one engine's internals (Requirement 14.1). boltstore.DB is the only engine today.

The contract is the Store interface declared BELOW, in this package. That is deliberate: a contract suite is the one consumer for which a wide store interface is the honest shape, because the suite's whole job is to exercise the surface an engine must implement. Every other consumer in the app takes the two to seven methods it calls.

What this suite is

Suite asserts EXACT observable values, not merely "does not error". A single suite pins every resolved finding from the bbolt-store-rewrite design review (Requirement 14.2):

  • the three ReconcileState branches (video gone; subtitle gone with a sibling still present; all subtitles gone),
  • non-destructive ClearManualLock (rows preserved, lock cleared),
  • backoff cleared on SaveDownload,
  • DeleteStateByPaths orphan cleanup (rows + backoff + coverage),
  • State filter / search / limit / offset,
  • both CleanupDrift branches (removed languages/providers, Requirement 7.7; adaptive disabled, Requirement 7.8).

Because it asserts exact values it requires a REAL persisting store: a no-op fake that discards writes cannot satisfy it, and the boltstore package proves the suite catches a regression by running one promoted invariant (AssertClearManualLockNonDestructive) against a deliberately broken stub and asserting the assertion fails.

Filesystem dependency

ReconcileState classifies each row against the real filesystem (an engine defaults its stat oracle to os.Stat), so the reconcile cases create real video/subtitle files under t.TempDir() and reference those paths. This keeps the suite engine-agnostic: it drives reconcile entirely through SaveDownload + RecordNoResult + RecordScanState and real files, with no engine-specific stat injection.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AssertClearManualLockNonDestructive added in v0.1.54

func AssertClearManualLockNonDestructive(t TB, s Store)

AssertClearManualLockNonDestructive asserts ClearManualLock is a NON-destructive flag flip: the lock is cleared but the rows are preserved and stay visible to State and DownloadedRefs (Requirement 4.3). It is exported and written against TB so the boltstore package can run it against a deliberately broken (destructive) stub and assert the assertion fails — proving the suite catches the regression.

func Suite

func Suite(t *testing.T, newStore func(t *testing.T) Store)

Suite runs the engine-agnostic behavioral contract against any Store produced by newStore. Each promoted finding is a NAMED subtest so a failure names the exact behaviour that regressed.

Types

type Store added in v0.4.0

type Store interface {
	// Adaptive backoff.
	RecordNoResult(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, providerName subflux.ProviderID, bp subflux.BackoffParams) error
	BackedOffProviders(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, maxAttempts int) ([]subflux.ProviderID, error)
	BackoffByPrefix(ctx context.Context, mediaType subflux.MediaType, mediaIDPrefix string) ([]subflux.BackoffEntry, error)

	// Download records and history.
	SaveDownload(ctx context.Context, rec *subflux.DownloadRecord) error
	DownloadedRefs(ctx context.Context, mediaType subflux.MediaType, mediaID, language string) ([]subflux.DownloadedRef, error)
	CurrentScore(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, variant subflux.Variant) (score int, mediaImported time.Time, found bool, err error)
	State(ctx context.Context, q *subflux.StateQuery) ([]subflux.StateEntry, error)

	// Manual locks and ordinals.
	IsManuallyLocked(ctx context.Context, key subflux.ManualLockKey) (bool, error)
	ClearManualLock(ctx context.Context, key subflux.ManualLockKey) error
	ManualDownloadCount(ctx context.Context, key subflux.ManualLockKey) (int, error)
	ManualSubtitlePaths(ctx context.Context, key subflux.ManualLockKey) ([]string, error)
	NextManualNumber(ctx context.Context, key subflux.ManualLockKey) int
	ManualLocks(ctx context.Context) ([]subflux.ManualLockEntry, error)

	// Coverage: subtitle files and scan state.
	RecordSubtitleFiles(ctx context.Context, mediaType subflux.MediaType, mediaID string, files []subflux.SubtitleFile) (bool, error)
	SubtitleFiles(ctx context.Context, mediaType subflux.MediaType, mediaIDPrefix string) ([]subflux.SubtitleEntry, error)
	RecordScanState(ctx context.Context, rec *subflux.ScanRecord) error
	ScanStates(ctx context.Context, mediaType subflux.MediaType, mediaIDPrefix string) ([]subflux.ScanStateRow, error)
	RecentlyScanned(ctx context.Context, cutoff time.Time) (map[string]bool, error)
	TotalSubtitleFiles(ctx context.Context) (int, error)

	// Sync offsets.
	SetSyncOffset(ctx context.Context, path string, offsetMs int64) error
	SyncOffset(ctx context.Context, path string) (int64, error)

	// Poll watermark.
	PollTimestamp(ctx context.Context, key subflux.PollKey) (time.Time, error)
	SetPollTimestamp(ctx context.Context, key subflux.PollKey, t time.Time) error

	// Maintenance.
	Stats(ctx context.Context) (downloads, attempts int, err error)
	DeleteStateByPaths(ctx context.Context, paths []string) (subflux.CleanupResult, error)
	CleanupDrift(ctx context.Context, drift subflux.ConfigDrift) error
	ReconcileState(ctx context.Context) (subflux.ReconcileResult, error)
}

Store is the surface this suite exercises: 27 of the 36 methods the concrete store exports. The nine it does not touch are BackoffItems, HistoryMediaIDs, UpsertSubtitleFile, DeleteSubtitleFile, LastScanTime, the three ScanCycleStart accessors, and Close — read paths and lifecycle that their own consumers' tests cover. Listing 27 rather than inheriting 36 is what makes that gap visible instead of implied.

This is the one interface in subflux that names a broad store surface, and it is declared here because this package IS its only consumer.

type TB added in v0.1.54

type TB interface {
	Helper()
	Errorf(format string, args ...any)
	Fatalf(format string, args ...any)
}

TB is the subset of *testing.T the reusable behavioural assertions need. Real callers pass *testing.T; the broken-stub self-check (in the boltstore package) passes a recorder that captures whether a failure was reported, proving the suite catches a non-conforming store without failing the parent test. *testing.T satisfies TB.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL