Bitrix Ci Laravel Package

Getting Started

sheerockoff/bitrix-ci is a stripped-down Bitrix kernel intended to let you boot enough of the platform (\Bitrix\Main, kernel constants, base autoloading) to run tests in CI without vendoring the full bitrix/ document root into your repository.

Minimal steps:

composer require --dev sheerockoff/bitrix-ci

Then wire a PHPUnit bootstrap that requires vendor/autoload.php before your test suites run. The package is require-dev-only by design — never let it leak into a production require block, because it only emulates the parts of Bitrix your tests touch.

Where to look first:

1. The package's own composer.json and autoload map — this tells you exactly which kernel namespaces are stubbed and which Bitrix classes will class_exists() return true for.
2. The package's tests/ directory (or its README example, if present) — the author's own bootstrap is the fastest reference for the minimum set of constants and includes needed to get a run green.
3. Your module's install/index.php and lib/ tree — that is where your testable logic should already live.

First use case to target: unit-testing a custom Bitrix module's business logic (event handlers, agents, service classes under \Vendor\Module\) that currently has no test coverage because "you can't run Bitrix in CI." Start with pure-PHP classes that only depend on \Bitrix\Main\Loader and \Bitrix\Main\Type\DateTime, then expand toward ORM once you decide how to handle the DB.

Implementation Patterns

Dedicated bootstrap file. Keep a tests/bootstrap.php that (a) requires the Composer autoloader, (b) defines the constants Bitrix's kernel expects (DOCUMENT_ROOT, BX_ROOT, BX_PERSONAL_ROOT, SITE_ID, LANG), and (c) optionally sets $_SERVER['DOCUMENT_ROOT']. Define these before any kernel class is autoloaded — late definitions cause the classic "constant already defined / undefined constant" fatal.

Globals stubbing in setUp(). Bitrix code reaching for global $APPLICATION, $DB, $USER, or $GLOBALS['APPLICATION'] will fatal on null. Two patterns work:

• Set lightweight stub objects in a base TestCase::setUp() for globals your code only calls methods on (GetCurPage(), GetMessage(), etc.).
• Or add a thin helper like bitrix_bootstrap() invoked once per process, populating globals lazily.

Mockery or hand-written anonymous classes both work; prefer hand-written stubs for the half-dozen methods you actually use, so upgrades to Bitrix don't silently break mocks.

Module autoloading. Register your module namespace in the root composer.json ("Vendor\\Module\\": "local/modules/vendor.module/lib/") rather than relying on Bitrix's Loader::includeModule. This keeps your CI independent of Bitrix's module registration machinery and makes the classes resolvable by PHPStan and IDEs too.

CI job shape. A single PHP-version matrix job is enough:

- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/phpunit --bootstrap tests/bootstrap.php

Cache ~/.composer/cache; the package is small, so install time is dominated by whatever test tooling you add.

Static analysis as the real win. Because the kernel is partial, running PHPStan (level 5–6) against local/modules/ with bitrix-ci on the autoload path is often more valuable than the unit tests themselves — it catches wrong \Bitrix\Main API usage without needing a full install.

Gotchas and Tips

It is archived with zero dependents. Pin the exact version ("sheerockoff/bitrix-ci": "1.0.x" or the specific tag), vendor it if your CI requires reproducible installs, and be prepared to fork. There will be no fixes for a PHP 8.4 deprecation or a Bitrix API drift.

Partial kernel ≠ running Bitrix. Components, templates, CBitrixComponent, and anything touching bitrix/templates or the site document root simply won't behave. Scope tests to \Bitrix\Main-level code and pure logic; do not attempt to integration-test component rendering through this.

Version drift is the silent killer. The kernel's \Bitrix\Main stubs correspond to whatever Bitrix release the author targeted (last release Oct 2024). If production runs a notably newer or older kernel, method signatures and return types may diverge — tests pass in CI, production fatals. Keep a note in the module README of the assumed Bitrix version.

Autoload collisions. If a developer has a real Bitrix install locally, both autoloaders can claim \Bitrix\Main\*. Make the CI bootstrap conditional (if (!class_exists(...))) or isolate the package to the CI job only, not the dev environment.

Constants defined too late. The most common failure mode is a fatal in the first test that only surfaces as an opaque Error in PHPUnit output. Run php -d error_reporting=E_ALL -d display_errors=1 vendor/bin/phpunit once locally when wiring the bootstrap; the real error appears immediately.

Extension points to lean on: your own tests/bootstrap.php, a shared BitrixTestCase base class, and a tests/stubs/ directory of hand-rolled $APPLICATION/$DB fakes. These are the only stable seams the package leaves you — treat everything inside vendor/sheerockoff/ as opaque.

Licensing caveat. The package itself is Unlicense, but the Bitrix kernel it mimics is proprietary 1C-Bitrix. Confirm that stubbing kernel interfaces for internal CI falls within your Bitrix license before distributing test fixtures publicly.