001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bct.junit;
018
019/**
020 * Wiring mode for a {@link TestBean @TestBean}-declared override.
021 *
022 * <p>
023 * Selects how the {@link JuneauBeanStoreExtension} threads the overlay into the system under test.  See
024 * {@link JuneauBeanStoreExtension} for the full {@link #INJECT} vs {@link #OVERLAY} contracts.
025 *
026 * <h5 class='section'>See Also:</h5><ul>
027 *    <li class='ja'>{@link TestBean} - The annotation that carries this mode selector.
028 *    <li class='jc'>{@link JuneauBeanStoreExtension} - The JUnit 5 extension that honors this mode.
029 * </ul>
030 *
031 * @since 10.0.0
032 */
033public enum Mode {
034
035   /**
036    * Construction-time wiring &mdash; the default.
037    *
038    * <p>
039    * The bean is wired into the SUT at construction time via the builder's
040    * {@code overridingBeanStore(...)} setter; the SUT doesn't exist until the overlay is applied.  The overlay is
041    * installed in the {@code overridingParent} slot of the SUT's bean store at construction time and is
042    * <i>universal</i> &mdash; every bean type is eligible for replacement, including framework-managed ones that
043    * subsequently pin into per-op memoizers.  Best for fresh-instance test isolation.
044    *
045    * <p>
046    * {@code INJECT} overrides do not require the extension to be
047    * {@linkplain JuneauBeanStoreExtension#attach(org.apache.juneau.commons.inject.WritableBeanStore) attached} to
048    * an existing bean store.
049    */
050   INJECT,
051
052   /**
053    * Push/pop wiring on a live SUT.
054    *
055    * <p>
056    * The bean is overlaid onto an already-constructed SUT for the duration of a test scope, then removed via
057    * {@link org.apache.juneau.commons.inject.WritableBeanStore#popOverlay(org.apache.juneau.commons.inject.Snapshot)}.
058    * Requires {@link JuneauBeanStoreExtension#attach(org.apache.juneau.commons.inject.WritableBeanStore)} to point
059    * the extension at the SUT's bean store; per-test overlays are pushed via
060    * {@link org.apache.juneau.commons.inject.WritableBeanStore#pushOverlay(org.apache.juneau.commons.inject.BeanStore)}
061    * at {@code beforeEach} / {@code beforeAll} and popped at {@code afterEach} / {@code afterAll}.  Best when SUT
062    * construction is expensive and tests share a live instance.
063    *
064    * <p>
065    * {@code OVERLAY} overrides only influence beans the framework resolves through the bean store per-call.  Beans
066    * pinned into per-op memoizers at boot are not re-resolved &mdash; for those, use {@link #INJECT} (fresh SUT).
067    */
068   OVERLAY
069}