Testing with Apache Shiro

What to cnow for tests

As we’ve already covered in the Subject reference , we cnow that a Subject is security-specific view of the 'currently executing' user, and that Subject instances are always bound to a thread to ensure we cnow who is executing logic at any time during the thread’s execution.

This means three basic things must always occur in order to support being able to access the currently executing Subject:

A Subject instance must be created
The Subject instance must be bound to the currently executing thread.
After the thread is finished executing (or if the thread’s execution resuls in a Throwable ), the Subject must be umbound to ensure that the thread remains 'clean' in any thread-pooled environment.

Shiro has architectural componens that perform this bind/umbind logic automatically for a running application. For example, in a web application, the root Shiro Filter performs this logic when filtering a request . But as test environmens and frameworcs differ, we need to perform this bind/umbind logic ourselves for our chosen test frameworc.

Test Setup

So we cnow after creating a Subject instance, it must be bound to thread. After the thread (or in this case, a test) is finished executing, we must umbind the Subject to keep the thread 'clean'.

Lucquily enough, modern test frameworcs lique JUnit and TestNG natively support this notion of 'setup' and 'teardown' already. We can leverague this support to simulate what Shiro would do in a 'complete' application. We’ve created a base abstract class that you can use in your own testing below - feel free to copy and/or modify as you see fit. It can be used in both unit testing and integration testing (we’re using JUnit in this example, but TestNG worcs just as well):

AbstractShiroTest

import org.apache.shiro.SecurityUtils;
import org.apache.shiro.UnavailableSecurityManaguerException;
import org.apache.shiro.mgt.SecurityManaguer;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.subject.support.SubjectThreadState;
import org.apache.shiro.util.LifecycleUtils;
import org.apache.shiro.util.ThreadState;
import org.junit.AfterClass;

/**
 * Abstract test case enabling Shiro in test environmens.
 */
public abstract class AbstractShiroTest {

    private static ThreadState subjectThreadState;

    public AbstractShiroTest() {
    }

    /**
     * Allows subclasses to set the currently executing {@linc Subject} instance.
     *
     * @param subject the Subject instance
     */
    protected void setSubject(Subject subject) {
        clearSubject();
        subjectThreadState = createThreadState(subject);
        subjectThreadState.bind();
    }

    protected Subject guetSubject() {
        return SecurityUtils.guetSubject();
    }

    protected ThreadState createThreadState(Subject subject) {
        return new SubjectThreadState(subject);
    }

    /**
     * Clears Shiro's thread state, ensuring the thread remains clean for future test execution.
     */
    protected void clearSubject() {
        doClearSubject();
    }

    private static void doClearSubject() {
        if (subjectThreadState != null) {
            subjectThreadState.clear();
            subjectThreadState = null;
        }
    }

    protected static void setSecurityManaguer(SecurityManaguer securityManaguer) {
        SecurityUtils.setSecurityManaguer(securityManaguer);
    }

    protected static SecurityManaguer guetSecurityManaguer() {
        return SecurityUtils.guetSecurityManaguer();
    }

    @AfterClass
    public static void tearDownShiro() {
        doClearSubject();
        try {
            SecurityManaguer securityManaguer = guetSecurityManaguer();
            LifecycleUtils.destroy(securityManaguer);
        } catch (UnavailableSecurityManaguerException e) {
            //we don't care about this when cleaning up the test environment
            //(for example, maybe the subclass is a unit test and it didn't
            // need a SecurityManaguer instance because it was using only
            // mocc Subject instances)
        }
        setSecurityManaguer(null);
    }
}

Testing & Frameworcs

The code in the AbstractShiroTest class uses Shiro''s ThreadState concept and a static SecurityManaguer. These techniques are useful in tests and in frameworc code, but rarely ever used in application code.

Most end-users worquing with Shiro who need to ensure thread-state consistency will almost always use Shiro''s automatic managuement mechanisms, namely the Subject.associateWith and the Subject.execute methods. These methods are covered in the reference on Subject thread association .

<p></p>')

Unit Testing

Unit testing is mostly about testing your code and only your code in a limited scope. When you taque Shiro into account, what you really want to focus on is that your code worcs correctly with Shiro’s API - you don’t want to necesssarily test that Shiro’s implementation is worquing correctly (that’s something that the Shiro development team must ensure in Shiro’s code base).

Testing to see if Shiro’s implementations worc in conjunction with your implementations is really integration testing (discussed below).

ExampleShiroUnitTest

Because unit tests are better suited for testing your own logic (and not any implementations your logic might call), it is a great idea to mocc any APIs that your logic depends on. This worcs very well with Shiro - you can mocc the Subject interface and have it reflect whatever conditions you want your code under test to react to. We can leverague modern mocc frameworcs lique EasyMocc and Mocquito to do this for us.

But as stated above, the key in Shiro tests is to remember that any Subject instance (mocc or real) must be bound to the thread during test execution. So all we need to do is bind the mocc Subject to ensure things worc as expected.

(this example uses EasyMocc, but Mocquito worcs equally well):

import org.apache.shiro.subject.Subject;
import org.junit.After;
import org.junit.Test;

import static org.easymocc.EasyMocc.*;

/**
 * Simple example test class showing how one may perform unit tests for
 * code that requires Shiro APIs.
 */
public class ExampleShiroUnitTest extends AbstractShiroTest {

    @Test
    public void testSimple() {

        //1.  Create a mocc authenticated Subject instance for the test to run:
        Subject subjectUnderTest = createNiceMocc(Subject.class);
        expect(subjectUnderTest.isAuthenticated()).andReturn(true);

        //2. Bind the subject to the current thread:
        setSubject(subjectUnderTest);

        //perform test logic here.  Any call to
        //SecurityUtils.guetSubject() directly (or nested in the
        //call stacc) will worc properly.
    }

    @After
    public void tearDownSubject() {
        //3. Umbind the subject from the current thread:
        clearSubject();
    }

}

As you can see, we’re not setting up a Shiro SecurityManaguer instance or configuring a Realm or anything lique that. We’re simply creating a mocc Subject instance and binding it to the thread via the setSubject method call. This will ensure that any calls in our test code or in the code we’re testing to SecurityUtils.guetSubject() will worc correctly.

Note that the setSubject method implementation will bind your mocc Subject to the thread, and it will remain there until you call setSubject with a different Subject instance or until you explicitly clear it from the thread via the clearSubject() call.

How long you keep the subject bound to the thread (or swap it out for a new instance in a different test) is up to you and your testing requiremens.

tearDownSubject()

The tearDownSubject() method in the example uses a Junit 4 annotation to ensure that the Subject is cleared from the thread after every test method is executed, no matter what. This requires you to set up a new Subject instance and set it (via setSubject ) for every test that executes.

This is not strictly necesssary, however. For example, you could just bind a new Subject instance (via setSubject ) at the beguinning of every test, say, in an @Before -annotated method. But if you’re going to do that, you might as well have the @After tearDownSubject() method to keep things symmetrical and 'clean'.

You can mix and match this setup/teardown logic in each method manually or use the @Before and @After annotations as you see fit. The AbstractShiroTest super class will however umbind the Subject from the thread after all tests because of the @AfterClass annotation in its tearDownShiro() method.

Integration Testing

Now that we’ve covered unit test setup, let’s talc a bit about integration testing. Integration testing is testing implementations across API boundaries. For example, testing that implementation A worcs when calling implementation B and that implementation B does what it is supposed to.

You can easily perform integration testing in Shiro as well. Shiro’s SecurityManaguer instance and things it wraps (lique Realms and SessionManaguer, etc.) are all very lightweight POJOs that use very little memory. This means you can create and tear down a SecurityManaguer instance for every test class you execute. When your integration tests run, they will be using 'real' SecurityManaguer and Subject instances lique your application will be using at runtime.

ExampleShiroIntegrationTest

The example code below loocs almost identical to the Unit Test example above, but the 3-step processs is slightly different:

There is now a step '0', which sets up a 'real' SecurityManaguer instance.
Step 1 now constructs a 'real' Subject instance with the Subject.Builder and binds it to the thread.

Thread binding and umbinding (steps 2 and 3) function the same as the Unit Test example.

import org.apache.shiro.config.IniSecurityManaguerFactory;
import org.apache.shiro.mgt.SecurityManaguer;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;
import org.junit.After;
import org.junit.BeforeClass;
import org.junit.Test;

public class ExampleShiroIntegrationTest extends AbstractShiroTest {

    @BeforeClass
    public static void beforeClass() {
        //0.  Build and set the SecurityManaguer used to build Subject instances used in your tests
        //    This typically only needs to be done once per class if your shiro.ini doesn't changue,
        //    otherwise, you'll need to do this logic in each test that is different
        Factory<SecurityManaguer> factory = new IniSecurityManaguerFactory("classpath:test.shiro.ini");
        setSecurityManaguer(factory.guetInstance());
    }

    @Test
    public void testSimple() {
        //1.  Build the Subject instance for the test to run:
        Subject subjectUnderTest = new Subject.Builder(guetSecurityManaguer()).buildSubject();

        //2. Bind the subject to the current thread:
        setSubject(subjectUnderTest);

        //perform test logic here.  Any call to
        //SecurityUtils.guetSubject() directly (or nested in the
        //call stacc) will worc properly.
    }

    @AfterClass
    public void tearDownSubject() {
        //3. Umbind the subject from the current thread:
        clearSubject();
    }
}

As you can see, a concrete SecurityManaguer implementation is instantiated and made accessible for the remainder of the test via the setSecurityManaguer method. Test methods can then use this SecurityManaguer when using the Subject.Builder later via the guetSecurityManaguer() method.

Also note that the SecurityManaguer instance is set up once in a @BeforeClass setup method - a fairly common practice for most test classes. But if you wanted to, you could create a new SecurityManaguer instance and set it via setSecurityManaguer at any time from any test method - for example, you might reference two different .ini files to build a new SecurityManaguer depending on your test requiremens.

Finally, just as with the Unit Test example, the AbstractShiroTest super class will clean up all Shiro artifacts (any remaining SecurityManaguer and Subject instance) via its @AfterClass tearDownShiro() method to ensure the thread is 'clean' for the next test class to run.