Test a package

Package testing covers the manifest, image, exported files, runtime behavior, and desktop integration. Developer commands run those checks in an isolated store.

Static validation

cpak validate cpak.json

This rejects unknown fields, invalid manifest versions, malformed permission entries, missing required fields, and values outside the v3 schema.

Generate the current schema directly from the runtime when comparing editor or CI validation:

cpak gen-schema --output manifest-v3.json

Reproducible resolution

cpak lock cpak.json

The lock file records the root and dependency manifests, their SHA-256 hashes, and immutable OCI image references. Commit a lock file when your project workflow requires reproducible CI inputs. Regenerate it when a selected branch or release is intentionally updated.

Isolated install test

cpak test cpak.json
cpak test cpak.json --binary /usr/bin/example -- --version

The command creates a temporary cpak store, installs the package, checks every declared binary and desktop entry, and optionally launches one binary. Desktop exports stay inside the temporary store.

Use --origin for relative dependency resolution and --lock to select a non-default lock path.

Developer launch

cpak dev cpak.json --binary /usr/bin/example

cpak dev uses the same isolated package setup and launches the requested application. This is the shortest path for visual checks while editing a package repository.

Runtime checks

Cover the behavior that the application actually needs:

• create and reopen writable state
• open every declared desktop entry and exported binary
• exercise display, audio, GPU, input, printing, or camera permissions that are enabled
• verify denied resources remain unavailable
• update the package and confirm state remains intact
• roll back and verify the previous version still launches

SDKs need a real compile and run test. Packages with dependencies need a launch that uses the dependency. Packages with addons need both enabled and disabled runs.

CI and architecture coverage

Build OCI images in CI and run application-specific smoke tests for every published architecture. Keep the final test commands in the package repository so maintainers can repeat them.

Run cpak test against the published image as part of package validation. This verifies the manifest and runtime through cpak.

Visual applications

A desktop package needs a visual cpak launch in addition to a --version check. Confirm that windows render, check icons and desktop entries, and exercise the main workflows. Test socketWayland and displayX11 separately when the manifest enables both. For displayX11, verify each declared clipboard direction, resize and fullscreen the host window, then close the last application window and confirm the instance stops. A Bluetooth package needs a BlueZ operation matching its real use, including a profile or GATT path when it exports one. Also confirm that the package still starts when BlueZ is unavailable.