README

Start here

This is a Composer extension for PAM Native. Install the PAM Runtime, create a native project, and then add this package through PAM’s verified Composer toolchain:

curl --proto '=https' --proto-redir '=https' --tlsv1.2 \
    --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSL \
    https://github.com/push-in/pam/releases/latest/download/install.sh | sh

pam init my-app --template native
cd my-app
pam composer require pushinbr/pam-native-testing
pam doctor --fix

Deterministic, strict bridge testing for PAM Native applications and plugins.

pam add testing
pam doctor

$native = NativeTestHarness::install();
$native->succeed('auth.session', 'current', [
    'identifier' => 'user-1',
    'state' => 2,
]);

// Exercise production PHP code.

$native->assertCalled('auth.session', 'current');
$native->assertSatisfied();
NativeTestHarness::uninstall();

Responses can be immediate or deferred. Unstubbed calls fail immediately, and assertSatisfied() detects unused responses and unflushed completions.

What installation does

pam add testing resolves the official compatible package, performs a non-mutating Composer preflight, updates the normal composer.json and composer.lock, refreshes generated native integration when required, and leaves the project ready for pam doctor validation.

Use pam packages to inspect availability and pam remove testing to uninstall the capability safely. Direct Composer commands are an advanced interoperability path; PAM is the supported application workflow.

API guide

API	Responsibility
`NativeTestHarness`	Install and remove the fake native-module transport.
`FakeNativeModuleTransport`	Stub success/failure, record calls, defer responses, and assert completion.
`DispatchMode`	Choose immediate or deferred callback execution.
`RecordedModuleCall`	Inspect exact module, method, and payload calls.
`StubbedModuleResponse`	Describe deterministic native results.

All coded states, kinds, and variants are sequential integer-backed enums. Use enum cases in application code; do not depend on raw wire numbers.

Production checklist

Uninstall the harness during test teardown.
Fail every unstubbed native call so tests cannot pass accidentally.
Call assertSatisfied() to catch unused responses and pending completions.
Run pam doctor, pam test, and a signed release build on every supported platform.
Exercise denial, cancellation, backgrounding, process restart, and offline behavior before release.

Troubleshooting

A test hangs: flush deferred responses or change the dispatch mode.
An assertion sees extra calls: reset or reinstall the harness per test.
Production transport leaks between tests: enforce teardown even after failures.
Native integration is stale: run pam doctor --fix, rebuild the native host, and inspect the first reported diagnostic.

Compatibility and support

This package targets PAM Native 0.6.x, Android API 26+, and iOS 15+ unless a platform-specific section above states a stricter requirement. Platform SDKs, credentials, entitlements, physical hardware, and store configuration remain application responsibilities.

Security vulnerabilities should be reported through the repository security policy or GitHub private vulnerability reporting, not a public issue.

pushinbr / pam-native-testing

Maintainers

Package info

Statistics

Security