/*
 * Copyright 2012-present Facebook, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License. You may obtain
 * a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */

package com.facebook.buck.rules;

import com.facebook.buck.step.ExecutionContext;
import com.facebook.buck.step.Step;
import com.facebook.buck.test.TestCaseSummary;
import com.facebook.buck.test.TestResultSummary;
import com.facebook.buck.test.TestResults;
import com.facebook.buck.test.TestRunningOptions;
import com.facebook.buck.test.TestStatusMessage;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.Callable;

/** A {@link BuildRule} that is designed to run tests. */
public interface TestRule extends BuildRule {

  /**
   * Callbacks to invoke during the test run to report information about test cases and/or tests.
   */
  interface TestReportingCallback {
    void testsDidBegin();

    void statusDidBegin(TestStatusMessage status);

    void statusDidEnd(TestStatusMessage status);

    void testDidBegin(String testCaseName, String testName);

    void testDidEnd(TestResultSummary testResultSummary);

    void testsDidEnd(List<TestCaseSummary> testCaseSummaries);
  }

  /** Implementation of {@link TestReportingCallback} which does nothing. */
  TestReportingCallback NOOP_REPORTING_CALLBACK =
      new TestReportingCallback() {
        @Override
        public void testsDidBegin() {}

        @Override
        public void testDidBegin(String testCaseName, String testName) {}

        @Override
        public void statusDidBegin(TestStatusMessage status) {}

        @Override
        public void statusDidEnd(TestStatusMessage status) {}

        @Override
        public void testDidEnd(TestResultSummary testResultSummary) {}

        @Override
        public void testsDidEnd(List<TestCaseSummary> testCaseSummaries) {}
      };

  /**
   * Returns the commands required to run the tests.
   *
   * <p><strong>Note:</strong> This method may be run without {@link
   * BuildEngine#build(BuildEngineBuildContext, ExecutionContext, BuildRule)} having been run. This
   * happens if the user has built [and ran] the test previously and then re-runs it using the
   * {@code --debug} flag.
   *
   * @param executionContext Provides context for creating {@link Step}s.
   * @param options The runtime testing options.
   * @param pathResolver A SourcePathResolver from the build.
   * @return the commands required to run the tests
   */
  ImmutableList<Step> runTests(
      ExecutionContext executionContext,
      TestRunningOptions options,
      SourcePathResolver pathResolver,
      TestReportingCallback testReportingCallback);

  Callable<TestResults> interpretTestResults(
      ExecutionContext executionContext, boolean isUsingTestSelectors);

  /** @return The set of labels for this build rule. */
  ImmutableSet<String> getLabels();

  /** @return The set of email addresses to act as contact points for this test. */
  ImmutableSet<String> getContacts();

  /** @return The relative path to the output directory of the test rule. */
  Path getPathToTestOutputDirectory();

  /** @return true if the test should run by itself when no other tests are run, false otherwise. */
  boolean runTestSeparately();

  /**
   * @return true if calling {@code runTests()} on this rule invokes the callbacks in {@code
   *     testReportingCallback} as the tests run, false otherwise.
   */
  boolean supportsStreamingTests();
}