Securing Magento Adminhtml Controllers with PHPUnit

1. Why adminhtml controllers need a distinct test level

An adminhtml controller in Magento typically extends Magento\Backend\App\Action and bundles several responsibilities: the ACL check via the _isAllowed() method, reading and validating form data from the request, calling the actual business logic, and setting success or error messages plus the redirect decision. This bundling naturally makes the controller a harder unit to isolate than a plain service class.

That is why a two-tier test approach pays off here: a plain unit test checks the decision logic inside the execute() method with a mocked request, response, and session, while a Magento integration test that extends \Magento\TestFramework\TestCase\AbstractBackendController checks the actual routing, ACL resolution against the real permission structure, and the complete dispatching. Both levels complement rather than replace each other.

2. Structuring a testable adminhtml controller

For a controller to be meaningfully unit-testable at all, the actual processing of form data should not happen directly in execute(), but be delegated to an injected service. The controller itself stays responsible for reading request parameters, calling the service, and deciding on the response. That is the same principle as with cron jobs and queue consumers: a thin entry layer with the domain logic extracted.

In addition, the ACL resource should be defined explicitly as a constant and referenced in _isAllowed(), instead of hardcoding the string directly. That makes it easier to check precisely in a test which resource is required for the controller, and prevents typos between the controller class and acl.xml.

<?php
declare(strict_types=1);

namespace Mironsoft\SeoSuite\Controller\Adminhtml\Redirect;

use Magento\Backend\App\Action;
use Magento\Framework\Controller\ResultFactory;
use Mironsoft\SeoSuite\Model\RedirectSaver;

/**
 * Saves a new redirect rule in the admin backend.
 */
class Save extends Action
{
    public const ADMIN_RESOURCE = 'Mironsoft_SeoSuite::redirect_save';

    public function __construct(
        Action\Context $context,
        private readonly RedirectSaver $redirectSaver
    ) {
        parent::__construct($context);
    }

    /**
     * Processes the form data and saves the redirect.
     *
     * @return \Magento\Framework\Controller\ResultInterface
     */
    public function execute()
    {
        $data = $this->getRequest()->getParams();
        $resultRedirect = $this->resultFactory->create(ResultFactory::TYPE_REDIRECT);

        if (empty($data['from_path']) || empty($data['to_path'])) {
            $this->messageManager->addErrorMessage(__('Please fill in all required fields.'));
            return $resultRedirect->setPath('*/*/new');
        }

        $this->redirectSaver->save($data['from_path'], $data['to_path']);
        $this->messageManager->addSuccessMessage(__('The redirect has been saved.'));

        return $resultRedirect->setPath('*/*/');
    }
}

3. Testing the execute logic as a unit test with a mocked request

For the plain unit test, the controller is not invoked through dispatching but instantiated directly, with the context, request, message manager, and injected service all mocked. The test then checks whether, on missing required fields, the error message is set and the redirect goes to the right page, without the save service ever being called.

This test runs without a database and without real HTTP routing, in milliseconds. It covers the actual decision logic: which conditions lead to which redirect, which message is set, is the service called with the expected parameters. This is the same test strategy as for any other service class, just with the controller-specific mocks for request and message manager.

<?php
declare(strict_types=1);

namespace Mironsoft\SeoSuite\Test\Unit\Controller\Adminhtml\Redirect;

use Mironsoft\SeoSuite\Controller\Adminhtml\Redirect\Save;
use Mironsoft\SeoSuite\Model\RedirectSaver;
use Magento\Backend\App\Action\Context;
use Magento\Framework\App\RequestInterface;
use Magento\Framework\Message\ManagerInterface;
use Magento\Framework\Controller\Result\Redirect;
use Magento\Framework\Controller\ResultFactory;
use PHPUnit\Framework\TestCase;

class SaveTest extends TestCase
{
    public function testMissingRequiredFieldsShowsErrorAndRedirectsToNew(): void
    {
        $request = $this->createMock(RequestInterface::class);
        $request->method('getParams')->willReturn(['from_path' => '', 'to_path' => '']);

        $messageManager = $this->createMock(ManagerInterface::class);
        $messageManager->expects($this->once())->method('addErrorMessage');

        $redirectResult = $this->createMock(Redirect::class);
        $redirectResult->expects($this->once())->method('setPath')->with('*/*/new')->willReturnSelf();

        $resultFactory = $this->createMock(ResultFactory::class);
        $resultFactory->method('create')->willReturn($redirectResult);

        $context = $this->createMock(Context::class);
        $context->method('getRequest')->willReturn($request);
        $context->method('getMessageManager')->willReturn($messageManager);
        $context->method('getResultFactory')->willReturn($resultFactory);

        $redirectSaver = $this->createMock(RedirectSaver::class);
        $redirectSaver->expects($this->never())->method('save');

        $controller = new Save($context, $redirectSaver);
        $controller->execute();
    }
}

4. Testing ACL checks as an integration test against the real permission structure

While the unit test checks the core logic, actual ACL enforcement can only be meaningfully tested against the real Magento permission structure, because that is where it is verified whether a user with a given role gets access to the resource configured in acl.xml or is rejected with a 403 response. Magento provides the base class AbstractBackendController in the TestFramework for this, which realistically reproduces dispatching, session, and authorization.

Such an integration test simulates an admin user without the required resource and checks that access is denied, as well as a user with the resource, for whom the action succeeds. This test is noticeably slower than a unit test because it requires the full Magento bootstrap, but in return it covers exactly the spot where a pure unit test would be blind: the interplay of controller, acl.xml, and role management.

<?php
declare(strict_types=1);

namespace Mironsoft\SeoSuite\Test\Integration\Controller\Adminhtml\Redirect;

use Magento\TestFramework\TestCase\AbstractBackendController;

/**
 * @magentoAppArea adminhtml
 */
class SaveTest extends AbstractBackendController
{
    /**
     * @magentoConfigFixture current_store admin/security/admin_account_sharing 0
     */
    public function testAclHasAccess(): void
    {
        $this->dispatch('backend/mironsoft_seosuite/redirect/save');
        $this->assertSessionMessages($this->equalTo([]));
    }

    public function testAclNoAccess(): void
    {
        $this->getRequest()->setParam('form_key', $this->_objectManager->get(
            \Magento\Framework\Data\Form\FormKey::class
        )->getFormKey());
        $this->uri = 'backend/mironsoft_seosuite/redirect/save';
        parent::testAclNoAccess();
    }
}

5. Testing form validation as a standalone, isolated rule

If the validation logic is more complex than a simple empty-string check, for instance a rule that from_path must start with a slash and must not be identical to to_path, it pays off to extract that validation into its own validator class. The controller then simply calls validate() and reacts to the result, while the actual rule set lives in its own fine-grained test set.

This separation makes it possible to run through many validation variants via a data provider without building up the full controller context every time. If a validation rule changes, only the validator test needs adjusting, while the controller test stays unchanged as long as the interface to the validator remains the same.

<?php
declare(strict_types=1);

/**
 * @dataProvider invalidRedirectDataProvider
 */
public function testValidatorRejectsInvalidRedirectRules(string $from, string $to, string $expectedError): void
{
    $validator = new RedirectRuleValidator();
    $result = $validator->validate($from, $to);

    $this->assertFalse($result->isValid());
    $this->assertSame($expectedError, $result->getFirstError());
}

public static function invalidRedirectDataProvider(): array
{
    return [
        'missing leading slash' => ['catalog/product', '/new-path', 'from_path must start with a slash'],
        'identical paths' => ['/old-path', '/old-path', 'from_path and to_path must differ'],
    ];
}

6. Precisely checking redirect targets and message types

A common bug in adminhtml controllers is a wrong redirect target after saving, for instance when clicking Save and Continue accidentally redirects to the list view instead of the edit page. Such bugs often go unnoticed during manual testing because both sides return valid responses, just the wrong one in that particular context.

A targeted unit test that checks, for every request parameter such as the save-and-continue button, the expected redirect target reliably catches exactly this class of bugs. Combined with a check of the message type, meaning whether addSuccessMessage was actually called instead of addErrorMessage, this results in a precise specification of the visible user behavior.

<?php
declare(strict_types=1);

public function testSaveAndContinueRedirectsToEditPageWithId(): void
{
    $request = $this->createMock(RequestInterface::class);
    $request->method('getParams')->willReturn([
        'from_path' => '/old', 'to_path' => '/new', 'back' => 'edit', 'entity_id' => '5',
    ]);

    $redirectResult = $this->createMock(Redirect::class);
    $redirectResult->expects($this->once())->method('setPath')->with('*/*/edit', ['id' => '5'])->willReturnSelf();

    // ... context setup analogous to the previous test ...
    $this->assertTrue(true);
}

7. Drawing the line to full functional and MFTF tests

PHPUnit tests, whether unit or integration, always check PHP-side behavior: is the right method called, is the right redirect set, does the ACL configuration match. What PHPUnit deliberately does not cover is the actual rendering of the adminhtml UI in a browser, JavaScript interactions in the UI component form, or the visual layout of the page.

For those aspects, MFTF, the Magento Functional Testing Framework, is the right level, because it drives a real browser and runs through the complete stack from HTML through JavaScript to the database. In practice a clear division of labor proves effective: PHPUnit covers the logic cases with many small, fast tests, while MFTF secures a few but critical end-to-end paths, such as successfully creating a record through the UI.

8. Common testing pitfalls with adminhtml controllers

A common pitfall is using the ObjectManager directly inside the controller to create dependencies instead of injecting them through the constructor. That makes the controller practically unmockable in a unit test, because the actually used instance is only resolved at runtime in the real container. Every dependency should therefore be declared explicitly in the constructor, even if that initially seems more cumbersome for controllers with many instance variables.

A second common pitfall is accidentally using real session or cookie objects in tests instead of mocking them, which leads to unpredictable behavior depending on what state was left over from a previous test. Consistently mocking all backend app context dependencies reliably prevents such hard-to-reproduce test failures.

9. Checklist and test levels at a glance

Anyone developing new adminhtml controllers should, from the start, extract business logic and validation into their own services, define ACL constants explicitly, and write a targeted unit test for every execute branch. ACL enforcement itself belongs in a lean integration test, while the visual behavior of the UI stays reserved for MFTF.

The table below places the different test levels around adminhtml controllers in context and shows which level covers which aspect of the controller.

10. Summary

11. FAQ: Testing Adminhtml Controllers: Key Takeaways