1 /*
2  * Copyright (C) 2023 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.tools.metalava.model.testsuite
18 
19 import com.android.tools.lint.checks.infrastructure.TestFile
20 import com.android.tools.metalava.model.Codebase
21 import com.android.tools.metalava.model.ModelOptions
22 import com.android.tools.metalava.model.provider.FilterableCodebaseCreator
23 import com.android.tools.metalava.model.provider.InputFormat
24 import java.io.File
25 
26 /**
27  * An API that defines a service which model test implementations must provide.
28  *
29  * An instance of this will be retrieved using the [ServiceLoader] mechanism.
30  */
31 interface ModelSuiteRunner : FilterableCodebaseCreator {
32 
33     /** Defines a specific test configuration for which the model tests should be run. */
34     data class TestConfiguration(
35         val inputFormat: InputFormat,
36         val modelOptions: ModelOptions = ModelOptions.empty,
37     )
38 
39     /**
40      * The [TestConfiguration]s of this [ModelSuiteRunner] for which the model suite tests must be
41      * run.
42      *
43      * Defaults to just one per [supportedInputFormats].
44      */
45     val testConfigurations
<lambda>null46         get() = supportedInputFormats.map { TestConfiguration(it) }.toList()
47 
48     /** A source directory and its contents. */
49     data class SourceDir(
50         /** The directory in which [contents] will be created. */
51         val dir: File,
52 
53         /** The contents of [dir]. */
54         val contents: List<TestFile>,
55     ) {
<lambda>null56         fun createFiles() = contents.map { it.createFile(dir) }
57     }
58 
59     /** Inputs for the test. */
60     data class TestInputs(
61         /**
62          * The [InputFormat] of the files in [mainSourceDir] and [commonSourceDir]. If they contain
63          * at least one Kotlin files then this will be [InputFormat.KOTLIN], otherwise it will be
64          * [InputFormat.JAVA].
65          */
66         val inputFormat: InputFormat,
67 
68         /** Model options to pass down to the model runner. */
69         val modelOptions: ModelOptions,
70 
71         /** The main sources that will be loaded into the [Codebase] to be tested. */
72         val mainSourceDir: SourceDir,
73 
74         /**
75          * Additional sources that will be created but will not be passed directly to the code being
76          * tested. Instead, the [SourceDir.dir] will be added to the source path which the code
77          * being tested may search implicitly.
78          */
79         val additionalMainSourceDir: SourceDir?,
80 
81         /** The optional common sources. */
82         val commonSourceDir: SourceDir?,
83 
84         /** Additional information to provide to the test runner. */
85         val testFixture: BaseModelTest.TestFixture,
86     )
87 
88     /**
89      * Create a [Codebase] from the supplied [inputs] and then run a test on that [Codebase].
90      *
91      * Implementations of this consume [inputs] to create a [Codebase] on which the test is run.
92      */
createCodebaseAndRunnull93     fun createCodebaseAndRun(
94         inputs: TestInputs,
95         test: (Codebase) -> Unit,
96     )
97 
98     /** The name of the runner used in parameterized test names. */
99     override fun toString(): String
100 }
101