blob: 6e4819c2c2505c26a2000e39c3ca729442d3f165 [file] [log] [blame]
Paul Duffin35816122021-02-24 01:49:52 +00001// Copyright 2021 Google Inc. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package android
16
17import (
Paul Duffinbbccfcf2021-03-03 00:44:00 +000018 "fmt"
Paul Duffin80f4cea2021-03-16 14:08:00 +000019 "strings"
Paul Duffin35816122021-02-24 01:49:52 +000020 "testing"
21)
22
23// Provides support for creating test fixtures on which tests can be run. Reduces duplication
24// of test setup by allow tests to easily reuse setup code.
25//
26// Fixture
27// =======
28// These determine the environment within which a test can be run. Fixtures are mutable and are
29// created by FixtureFactory instances and mutated by FixturePreparer instances. They are created by
30// first creating a base Fixture (which is essentially empty) and then applying FixturePreparer
31// instances to it to modify the environment.
32//
33// FixtureFactory
34// ==============
35// These are responsible for creating fixtures. Factories are immutable and are intended to be
36// initialized once and reused to create multiple fixtures. Each factory has a list of fixture
37// preparers that prepare a fixture for running a test. Factories can also be used to create other
38// factories by extending them with additional fixture preparers.
39//
40// FixturePreparer
41// ===============
42// These are responsible for modifying a Fixture in preparation for it to run a test. Preparers are
43// intended to be immutable and able to prepare multiple Fixture objects simultaneously without
44// them sharing any data.
45//
46// FixturePreparers are only ever invoked once per test fixture. Prior to invocation the list of
47// FixturePreparers are flattened and deduped while preserving the order they first appear in the
48// list. This makes it easy to reuse, group and combine FixturePreparers together.
49//
50// Each small self contained piece of test setup should be their own FixturePreparer. e.g.
51// * A group of related modules.
52// * A group of related mutators.
53// * A combination of both.
54// * Configuration.
55//
56// They should not overlap, e.g. the same module type should not be registered by different
57// FixturePreparers as using them both would cause a build error. In that case the preparer should
58// be split into separate parts and combined together using FixturePreparers(...).
59//
60// e.g. attempting to use AllPreparers in preparing a Fixture would break as it would attempt to
61// register module bar twice:
62// var Preparer1 = FixtureRegisterWithContext(RegisterModuleFooAndBar)
63// var Preparer2 = FixtureRegisterWithContext(RegisterModuleBarAndBaz)
Paul Duffina560d5a2021-02-28 01:38:51 +000064// var AllPreparers = GroupFixturePreparers(Preparer1, Preparer2)
Paul Duffin35816122021-02-24 01:49:52 +000065//
66// However, when restructured like this it would work fine:
67// var PreparerFoo = FixtureRegisterWithContext(RegisterModuleFoo)
68// var PreparerBar = FixtureRegisterWithContext(RegisterModuleBar)
69// var PreparerBaz = FixtureRegisterWithContext(RegisterModuleBaz)
Paul Duffina560d5a2021-02-28 01:38:51 +000070// var Preparer1 = GroupFixturePreparers(RegisterModuleFoo, RegisterModuleBar)
71// var Preparer2 = GroupFixturePreparers(RegisterModuleBar, RegisterModuleBaz)
72// var AllPreparers = GroupFixturePreparers(Preparer1, Preparer2)
Paul Duffin35816122021-02-24 01:49:52 +000073//
74// As after deduping and flattening AllPreparers would result in the following preparers being
75// applied:
76// 1. PreparerFoo
77// 2. PreparerBar
78// 3. PreparerBaz
79//
80// Preparers can be used for both integration and unit tests.
81//
82// Integration tests typically use all the module types, mutators and singletons that are available
83// for that package to try and replicate the behavior of the runtime build as closely as possible.
84// However, that realism comes at a cost of increased fragility (as they can be broken by changes in
85// many different parts of the build) and also increased runtime, especially if they use lots of
86// singletons and mutators.
87//
88// Unit tests on the other hand try and minimize the amount of code being tested which makes them
89// less susceptible to changes elsewhere in the build and quick to run but at a cost of potentially
90// not testing realistic scenarios.
91//
92// Supporting unit tests effectively require that preparers are available at the lowest granularity
93// possible. Supporting integration tests effectively require that the preparers are organized into
94// groups that provide all the functionality available.
95//
96// At least in terms of tests that check the behavior of build components via processing
97// `Android.bp` there is no clear separation between a unit test and an integration test. Instead
98// they vary from one end that tests a single module (e.g. filegroup) to the other end that tests a
99// whole system of modules, mutators and singletons (e.g. apex + hiddenapi).
100//
101// TestResult
102// ==========
103// These are created by running tests in a Fixture and provide access to the Config and TestContext
104// in which the tests were run.
105//
106// Example
107// =======
108//
109// An exported preparer for use by other packages that need to use java modules.
110//
111// package java
Paul Duffina560d5a2021-02-28 01:38:51 +0000112// var PrepareForIntegrationTestWithJava = GroupFixturePreparers(
Paul Duffin35816122021-02-24 01:49:52 +0000113// android.PrepareForIntegrationTestWithAndroid,
114// FixtureRegisterWithContext(RegisterAGroupOfRelatedModulesMutatorsAndSingletons),
115// FixtureRegisterWithContext(RegisterAnotherGroupOfRelatedModulesMutatorsAndSingletons),
116// ...
117// )
118//
119// Some files to use in tests in the java package.
120//
121// var javaMockFS = android.MockFS{
122// "api/current.txt": nil,
123// "api/removed.txt": nil,
124// ...
125// }
126//
127// A package private factory for use for testing java within the java package.
128//
129// var javaFixtureFactory = NewFixtureFactory(
130// PrepareForIntegrationTestWithJava,
131// FixtureRegisterWithContext(func(ctx android.RegistrationContext) {
132// ctx.RegisterModuleType("test_module", testModule)
133// }),
134// javaMockFS.AddToFixture(),
135// ...
136// }
137//
138// func TestJavaStuff(t *testing.T) {
139// result := javaFixtureFactory.RunTest(t,
140// android.FixtureWithRootAndroidBp(`java_library {....}`),
141// android.MockFS{...}.AddToFixture(),
142// )
143// ... test result ...
144// }
145//
146// package cc
Paul Duffina560d5a2021-02-28 01:38:51 +0000147// var PrepareForTestWithCC = GroupFixturePreparers(
Paul Duffin35816122021-02-24 01:49:52 +0000148// android.PrepareForArchMutator,
149// android.prepareForPrebuilts,
150// FixtureRegisterWithContext(RegisterRequiredBuildComponentsForTest),
151// ...
152// )
153//
154// package apex
155//
Paul Duffina560d5a2021-02-28 01:38:51 +0000156// var PrepareForApex = GroupFixturePreparers(
Paul Duffin35816122021-02-24 01:49:52 +0000157// ...
158// )
159//
160// Use modules and mutators from java, cc and apex. Any duplicate preparers (like
161// android.PrepareForArchMutator) will be automatically deduped.
162//
163// var apexFixtureFactory = android.NewFixtureFactory(
164// PrepareForJava,
165// PrepareForCC,
166// PrepareForApex,
167// )
168
169// Factory for Fixture objects.
170//
171// This is configured with a set of FixturePreparer objects that are used to
172// initialize each Fixture instance this creates.
173type FixtureFactory interface {
174
175 // Creates a copy of this instance and adds some additional preparers.
176 //
177 // Before the preparers are used they are combined with the preparers provided when the factory
178 // was created, any groups of preparers are flattened, and the list is deduped so that each
179 // preparer is only used once. See the file documentation in android/fixture.go for more details.
180 Extend(preparers ...FixturePreparer) FixtureFactory
181
182 // Create a Fixture.
183 Fixture(t *testing.T, preparers ...FixturePreparer) Fixture
184
Paul Duffin46e37742021-03-09 11:55:20 +0000185 // ExtendWithErrorHandler creates a new FixtureFactory that will use the supplied error handler
186 // to check the errors (may be 0) reported by the test.
Paul Duffincfd33742021-02-27 11:59:02 +0000187 //
188 // The default handlers is FixtureExpectsNoErrors which will fail the go test immediately if any
189 // errors are reported.
Paul Duffin46e37742021-03-09 11:55:20 +0000190 ExtendWithErrorHandler(errorHandler FixtureErrorHandler) FixtureFactory
Paul Duffincfd33742021-02-27 11:59:02 +0000191
192 // Run the test, checking any errors reported and returning a TestResult instance.
Paul Duffin35816122021-02-24 01:49:52 +0000193 //
194 // Shorthand for Fixture(t, preparers...).RunTest()
195 RunTest(t *testing.T, preparers ...FixturePreparer) *TestResult
196
197 // Run the test with the supplied Android.bp file.
198 //
199 // Shorthand for RunTest(t, android.FixtureWithRootAndroidBp(bp))
200 RunTestWithBp(t *testing.T, bp string) *TestResult
Paul Duffin72018ad2021-03-04 19:36:49 +0000201
202 // RunTestWithConfig is a temporary method added to help ease the migration of existing tests to
203 // the test fixture.
204 //
205 // In order to allow the Config object to be customized separately to the TestContext a lot of
206 // existing test code has `test...WithConfig` funcs that allow the Config object to be supplied
207 // from the test and then have the TestContext created and configured automatically. e.g.
208 // testCcWithConfig, testCcErrorWithConfig, testJavaWithConfig, etc.
209 //
210 // This method allows those methods to be migrated to use the test fixture pattern without
211 // requiring that every test that uses those methods be migrated at the same time. That allows
212 // those tests to benefit from correctness in the order of registration quickly.
213 //
214 // This method discards the config (along with its mock file system, product variables,
215 // environment, etc.) that may have been set up by FixturePreparers.
216 //
217 // deprecated
218 RunTestWithConfig(t *testing.T, config Config) *TestResult
Paul Duffin35816122021-02-24 01:49:52 +0000219}
220
221// Create a new FixtureFactory that will apply the supplied preparers.
222//
223// The buildDirSupplier is a pointer to the package level buildDir variable that is initialized by
224// the package level setUp method. It has to be a pointer to the variable as the variable will not
Paul Duffindff5ff02021-03-15 15:42:40 +0000225// have been initialized at the time the factory is created. If it is nil then a test specific
226// temporary directory will be created instead.
Paul Duffin35816122021-02-24 01:49:52 +0000227func NewFixtureFactory(buildDirSupplier *string, preparers ...FixturePreparer) FixtureFactory {
228 return &fixtureFactory{
229 buildDirSupplier: buildDirSupplier,
230 preparers: dedupAndFlattenPreparers(nil, preparers),
Paul Duffincfd33742021-02-27 11:59:02 +0000231
232 // Set the default error handler.
233 errorHandler: FixtureExpectsNoErrors,
Paul Duffin35816122021-02-24 01:49:52 +0000234 }
235}
236
237// A set of mock files to add to the mock file system.
238type MockFS map[string][]byte
239
Paul Duffin6e9a4002021-03-11 19:01:26 +0000240// Merge adds the extra entries from the supplied map to this one.
241//
242// Fails if the supplied map files with the same paths are present in both of them.
Paul Duffin35816122021-02-24 01:49:52 +0000243func (fs MockFS) Merge(extra map[string][]byte) {
244 for p, c := range extra {
Paul Duffin80f4cea2021-03-16 14:08:00 +0000245 validateFixtureMockFSPath(p)
Paul Duffin6e9a4002021-03-11 19:01:26 +0000246 if _, ok := fs[p]; ok {
247 panic(fmt.Errorf("attempted to add file %s to the mock filesystem but it already exists", p))
248 }
Paul Duffin35816122021-02-24 01:49:52 +0000249 fs[p] = c
250 }
251}
252
Paul Duffin80f4cea2021-03-16 14:08:00 +0000253// Ensure that tests cannot add paths into the mock file system which would not be allowed in the
254// runtime, e.g. absolute paths, paths relative to the 'out/' directory.
255func validateFixtureMockFSPath(path string) {
256 // This uses validateSafePath rather than validatePath because the latter prevents adding files
257 // that include a $ but there are tests that allow files with a $ to be used, albeit only by
258 // globbing.
259 validatedPath, err := validateSafePath(path)
260 if err != nil {
261 panic(err)
262 }
263
264 // Make sure that the path is canonical.
265 if validatedPath != path {
266 panic(fmt.Errorf("path %q is not a canonical path, use %q instead", path, validatedPath))
267 }
268
269 if path == "out" || strings.HasPrefix(path, "out/") {
270 panic(fmt.Errorf("cannot add output path %q to the mock file system", path))
271 }
272}
273
Paul Duffin35816122021-02-24 01:49:52 +0000274func (fs MockFS) AddToFixture() FixturePreparer {
275 return FixtureMergeMockFs(fs)
276}
277
Paul Duffinae542a52021-03-09 03:15:28 +0000278// FixtureCustomPreparer allows for the modification of any aspect of the fixture.
279//
280// This should only be used if one of the other more specific preparers are not suitable.
281func FixtureCustomPreparer(mutator func(fixture Fixture)) FixturePreparer {
282 return newSimpleFixturePreparer(func(f *fixture) {
283 mutator(f)
284 })
285}
286
Paul Duffin35816122021-02-24 01:49:52 +0000287// Modify the config
288func FixtureModifyConfig(mutator func(config Config)) FixturePreparer {
289 return newSimpleFixturePreparer(func(f *fixture) {
290 mutator(f.config)
291 })
292}
293
294// Modify the config and context
295func FixtureModifyConfigAndContext(mutator func(config Config, ctx *TestContext)) FixturePreparer {
296 return newSimpleFixturePreparer(func(f *fixture) {
297 mutator(f.config, f.ctx)
298 })
299}
300
301// Modify the context
302func FixtureModifyContext(mutator func(ctx *TestContext)) FixturePreparer {
303 return newSimpleFixturePreparer(func(f *fixture) {
304 mutator(f.ctx)
305 })
306}
307
308func FixtureRegisterWithContext(registeringFunc func(ctx RegistrationContext)) FixturePreparer {
309 return FixtureModifyContext(func(ctx *TestContext) { registeringFunc(ctx) })
310}
311
312// Modify the mock filesystem
313func FixtureModifyMockFS(mutator func(fs MockFS)) FixturePreparer {
314 return newSimpleFixturePreparer(func(f *fixture) {
315 mutator(f.mockFS)
Paul Duffin80f4cea2021-03-16 14:08:00 +0000316
317 // Make sure that invalid paths were not added to the mock filesystem.
318 for p, _ := range f.mockFS {
319 validateFixtureMockFSPath(p)
320 }
Paul Duffin35816122021-02-24 01:49:52 +0000321 })
322}
323
324// Merge the supplied file system into the mock filesystem.
325//
326// Paths that already exist in the mock file system are overridden.
327func FixtureMergeMockFs(mockFS MockFS) FixturePreparer {
328 return FixtureModifyMockFS(func(fs MockFS) {
329 fs.Merge(mockFS)
330 })
331}
332
333// Add a file to the mock filesystem
Paul Duffin6e9a4002021-03-11 19:01:26 +0000334//
335// Fail if the filesystem already contains a file with that path, use FixtureOverrideFile instead.
Paul Duffin35816122021-02-24 01:49:52 +0000336func FixtureAddFile(path string, contents []byte) FixturePreparer {
337 return FixtureModifyMockFS(func(fs MockFS) {
Paul Duffin80f4cea2021-03-16 14:08:00 +0000338 validateFixtureMockFSPath(path)
Paul Duffin6e9a4002021-03-11 19:01:26 +0000339 if _, ok := fs[path]; ok {
340 panic(fmt.Errorf("attempted to add file %s to the mock filesystem but it already exists, use FixtureOverride*File instead", path))
341 }
Paul Duffin35816122021-02-24 01:49:52 +0000342 fs[path] = contents
343 })
344}
345
346// Add a text file to the mock filesystem
Paul Duffin6e9a4002021-03-11 19:01:26 +0000347//
348// Fail if the filesystem already contains a file with that path.
Paul Duffin35816122021-02-24 01:49:52 +0000349func FixtureAddTextFile(path string, contents string) FixturePreparer {
350 return FixtureAddFile(path, []byte(contents))
351}
352
Paul Duffin6e9a4002021-03-11 19:01:26 +0000353// Override a file in the mock filesystem
354//
355// If the file does not exist this behaves as FixtureAddFile.
356func FixtureOverrideFile(path string, contents []byte) FixturePreparer {
357 return FixtureModifyMockFS(func(fs MockFS) {
358 fs[path] = contents
359 })
360}
361
362// Override a text file in the mock filesystem
363//
364// If the file does not exist this behaves as FixtureAddTextFile.
365func FixtureOverrideTextFile(path string, contents string) FixturePreparer {
366 return FixtureOverrideFile(path, []byte(contents))
367}
368
Paul Duffin35816122021-02-24 01:49:52 +0000369// Add the root Android.bp file with the supplied contents.
370func FixtureWithRootAndroidBp(contents string) FixturePreparer {
371 return FixtureAddTextFile("Android.bp", contents)
372}
373
Paul Duffinbbccfcf2021-03-03 00:44:00 +0000374// Merge some environment variables into the fixture.
375func FixtureMergeEnv(env map[string]string) FixturePreparer {
376 return FixtureModifyConfig(func(config Config) {
377 for k, v := range env {
378 if k == "PATH" {
379 panic("Cannot set PATH environment variable")
380 }
381 config.env[k] = v
382 }
383 })
384}
385
386// Modify the env.
387//
388// Will panic if the mutator changes the PATH environment variable.
389func FixtureModifyEnv(mutator func(env map[string]string)) FixturePreparer {
390 return FixtureModifyConfig(func(config Config) {
391 oldPath := config.env["PATH"]
392 mutator(config.env)
393 newPath := config.env["PATH"]
394 if newPath != oldPath {
395 panic(fmt.Errorf("Cannot change PATH environment variable from %q to %q", oldPath, newPath))
396 }
397 })
398}
399
Paul Duffin2e0323d2021-03-04 15:11:01 +0000400// Allow access to the product variables when preparing the fixture.
401type FixtureProductVariables struct {
402 *productVariables
403}
404
405// Modify product variables.
406func FixtureModifyProductVariables(mutator func(variables FixtureProductVariables)) FixturePreparer {
407 return FixtureModifyConfig(func(config Config) {
408 productVariables := FixtureProductVariables{&config.productVariables}
409 mutator(productVariables)
410 })
411}
412
Paul Duffina560d5a2021-02-28 01:38:51 +0000413// GroupFixturePreparers creates a composite FixturePreparer that is equivalent to applying each of
414// the supplied FixturePreparer instances in order.
415//
416// Before preparing the fixture the list of preparers is flattened by replacing each
417// instance of GroupFixturePreparers with its contents.
418func GroupFixturePreparers(preparers ...FixturePreparer) FixturePreparer {
Paul Duffin35816122021-02-24 01:49:52 +0000419 return &compositeFixturePreparer{dedupAndFlattenPreparers(nil, preparers)}
420}
421
Paul Duffin50deaae2021-03-16 17:46:12 +0000422// NullFixturePreparer is a preparer that does nothing.
423var NullFixturePreparer = GroupFixturePreparers()
424
425// OptionalFixturePreparer will return the supplied preparer if it is non-nil, otherwise it will
426// return the NullFixturePreparer
427func OptionalFixturePreparer(preparer FixturePreparer) FixturePreparer {
428 if preparer == nil {
429 return NullFixturePreparer
430 } else {
431 return preparer
432 }
433}
434
Paul Duffin35816122021-02-24 01:49:52 +0000435type simpleFixturePreparerVisitor func(preparer *simpleFixturePreparer)
436
437// FixturePreparer is an opaque interface that can change a fixture.
438type FixturePreparer interface {
439 // visit calls the supplied visitor with each *simpleFixturePreparer instances in this preparer,
440 visit(simpleFixturePreparerVisitor)
441}
442
443type fixturePreparers []FixturePreparer
444
445func (f fixturePreparers) visit(visitor simpleFixturePreparerVisitor) {
446 for _, p := range f {
447 p.visit(visitor)
448 }
449}
450
451// dedupAndFlattenPreparers removes any duplicates and flattens any composite FixturePreparer
452// instances.
453//
454// base - a list of already flattened and deduped preparers that will be applied first before
455// the list of additional preparers. Any duplicates of these in the additional preparers
456// will be ignored.
457//
458// preparers - a list of additional unflattened, undeduped preparers that will be applied after the
459// base preparers.
460//
461// Returns a deduped and flattened list of the preparers minus any that exist in the base preparers.
462func dedupAndFlattenPreparers(base []*simpleFixturePreparer, preparers fixturePreparers) []*simpleFixturePreparer {
463 var list []*simpleFixturePreparer
464 visited := make(map[*simpleFixturePreparer]struct{})
465
466 // Mark the already flattened and deduped preparers, if any, as having been seen so that
467 // duplicates of these in the additional preparers will be discarded.
468 for _, s := range base {
469 visited[s] = struct{}{}
470 }
471
472 preparers.visit(func(preparer *simpleFixturePreparer) {
473 if _, seen := visited[preparer]; !seen {
474 visited[preparer] = struct{}{}
475 list = append(list, preparer)
476 }
477 })
478 return list
479}
480
481// compositeFixturePreparer is a FixturePreparer created from a list of fixture preparers.
482type compositeFixturePreparer struct {
483 preparers []*simpleFixturePreparer
484}
485
486func (c *compositeFixturePreparer) visit(visitor simpleFixturePreparerVisitor) {
487 for _, p := range c.preparers {
488 p.visit(visitor)
489 }
490}
491
492// simpleFixturePreparer is a FixturePreparer that applies a function to a fixture.
493type simpleFixturePreparer struct {
494 function func(fixture *fixture)
495}
496
497func (s *simpleFixturePreparer) visit(visitor simpleFixturePreparerVisitor) {
498 visitor(s)
499}
500
501func newSimpleFixturePreparer(preparer func(fixture *fixture)) FixturePreparer {
502 return &simpleFixturePreparer{function: preparer}
503}
504
Paul Duffincfd33742021-02-27 11:59:02 +0000505// FixtureErrorHandler determines how to respond to errors reported by the code under test.
506//
507// Some possible responses:
508// * Fail the test if any errors are reported, see FixtureExpectsNoErrors.
509// * Fail the test if at least one error that matches a pattern is not reported see
510// FixtureExpectsAtLeastOneErrorMatchingPattern
511// * Fail the test if any unexpected errors are reported.
512//
513// Although at the moment all the error handlers are implemented as simply a wrapper around a
514// function this is defined as an interface to allow future enhancements, e.g. provide different
515// ways other than patterns to match an error and to combine handlers together.
516type FixtureErrorHandler interface {
517 // CheckErrors checks the errors reported.
518 //
519 // The supplied result can be used to access the state of the code under test just as the main
520 // body of the test would but if any errors other than ones expected are reported the state may
521 // be indeterminate.
Paul Duffinc81854a2021-03-12 12:22:27 +0000522 CheckErrors(t *testing.T, result *TestResult)
Paul Duffincfd33742021-02-27 11:59:02 +0000523}
524
525type simpleErrorHandler struct {
Paul Duffinc81854a2021-03-12 12:22:27 +0000526 function func(t *testing.T, result *TestResult)
Paul Duffincfd33742021-02-27 11:59:02 +0000527}
528
Paul Duffinc81854a2021-03-12 12:22:27 +0000529func (h simpleErrorHandler) CheckErrors(t *testing.T, result *TestResult) {
530 t.Helper()
531 h.function(t, result)
Paul Duffincfd33742021-02-27 11:59:02 +0000532}
533
534// The default fixture error handler.
535//
536// Will fail the test immediately if any errors are reported.
Paul Duffinea8a3862021-03-04 17:58:33 +0000537//
538// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
539// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000540var FixtureExpectsNoErrors = FixtureCustomErrorHandler(
Paul Duffinc81854a2021-03-12 12:22:27 +0000541 func(t *testing.T, result *TestResult) {
542 t.Helper()
543 FailIfErrored(t, result.Errs)
Paul Duffincfd33742021-02-27 11:59:02 +0000544 },
545)
546
Paul Duffin85034e92021-03-17 00:20:34 +0000547// FixtureIgnoreErrors ignores any errors.
548//
549// If this is used then it is the responsibility of the test to check the TestResult.Errs does not
550// contain any unexpected errors.
551var FixtureIgnoreErrors = FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
552 // Ignore the errors
553})
554
Paul Duffincfd33742021-02-27 11:59:02 +0000555// FixtureExpectsAtLeastOneMatchingError returns an error handler that will cause the test to fail
556// if at least one error that matches the regular expression is not found.
557//
558// The test will be failed if:
559// * No errors are reported.
560// * One or more errors are reported but none match the pattern.
561//
562// The test will not fail if:
563// * Multiple errors are reported that do not match the pattern as long as one does match.
Paul Duffinea8a3862021-03-04 17:58:33 +0000564//
565// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
566// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000567func FixtureExpectsAtLeastOneErrorMatchingPattern(pattern string) FixtureErrorHandler {
Paul Duffinc81854a2021-03-12 12:22:27 +0000568 return FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
569 t.Helper()
570 if !FailIfNoMatchingErrors(t, pattern, result.Errs) {
571 t.FailNow()
Paul Duffinea8a3862021-03-04 17:58:33 +0000572 }
Paul Duffincfd33742021-02-27 11:59:02 +0000573 })
574}
575
576// FixtureExpectsOneErrorToMatchPerPattern returns an error handler that will cause the test to fail
577// if there are any unexpected errors.
578//
579// The test will be failed if:
580// * The number of errors reported does not exactly match the patterns.
581// * One or more of the reported errors do not match a pattern.
582// * No patterns are provided and one or more errors are reported.
583//
584// The test will not fail if:
585// * One or more of the patterns does not match an error.
Paul Duffinea8a3862021-03-04 17:58:33 +0000586//
587// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
588// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000589func FixtureExpectsAllErrorsToMatchAPattern(patterns []string) FixtureErrorHandler {
Paul Duffinc81854a2021-03-12 12:22:27 +0000590 return FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
591 t.Helper()
592 CheckErrorsAgainstExpectations(t, result.Errs, patterns)
Paul Duffincfd33742021-02-27 11:59:02 +0000593 })
594}
595
596// FixtureCustomErrorHandler creates a custom error handler
Paul Duffinc81854a2021-03-12 12:22:27 +0000597func FixtureCustomErrorHandler(function func(t *testing.T, result *TestResult)) FixtureErrorHandler {
Paul Duffincfd33742021-02-27 11:59:02 +0000598 return simpleErrorHandler{
599 function: function,
600 }
601}
602
Paul Duffin35816122021-02-24 01:49:52 +0000603// Fixture defines the test environment.
604type Fixture interface {
Paul Duffinae542a52021-03-09 03:15:28 +0000605 // Config returns the fixture's configuration.
606 Config() Config
607
608 // Context returns the fixture's test context.
609 Context() *TestContext
610
611 // MockFS returns the fixture's mock filesystem.
612 MockFS() MockFS
613
Paul Duffincfd33742021-02-27 11:59:02 +0000614 // Run the test, checking any errors reported and returning a TestResult instance.
Paul Duffin35816122021-02-24 01:49:52 +0000615 RunTest() *TestResult
616}
617
Paul Duffin35816122021-02-24 01:49:52 +0000618// Struct to allow TestResult to embed a *TestContext and allow call forwarding to its methods.
619type testContext struct {
620 *TestContext
621}
622
623// The result of running a test.
624type TestResult struct {
Paul Duffin35816122021-02-24 01:49:52 +0000625 testContext
626
627 fixture *fixture
628 Config Config
Paul Duffin942481b2021-03-04 18:58:11 +0000629
630 // The errors that were reported during the test.
631 Errs []error
Paul Duffin78c36212021-03-16 23:57:12 +0000632
633 // The ninja deps is a list of the ninja files dependencies that were added by the modules and
634 // singletons via the *.AddNinjaFileDeps() methods.
635 NinjaDeps []string
Paul Duffin35816122021-02-24 01:49:52 +0000636}
637
638var _ FixtureFactory = (*fixtureFactory)(nil)
639
640type fixtureFactory struct {
641 buildDirSupplier *string
642 preparers []*simpleFixturePreparer
Paul Duffincfd33742021-02-27 11:59:02 +0000643 errorHandler FixtureErrorHandler
Paul Duffin35816122021-02-24 01:49:52 +0000644}
645
646func (f *fixtureFactory) Extend(preparers ...FixturePreparer) FixtureFactory {
Paul Duffinfa298852021-03-08 15:05:24 +0000647 // Create a new slice to avoid accidentally sharing the preparers slice from this factory with
648 // the extending factories.
649 var all []*simpleFixturePreparer
650 all = append(all, f.preparers...)
651 all = append(all, dedupAndFlattenPreparers(f.preparers, preparers)...)
Paul Duffincfd33742021-02-27 11:59:02 +0000652 // Copy the existing factory.
653 extendedFactory := &fixtureFactory{}
654 *extendedFactory = *f
655 // Use the extended list of preparers.
656 extendedFactory.preparers = all
657 return extendedFactory
Paul Duffin35816122021-02-24 01:49:52 +0000658}
659
660func (f *fixtureFactory) Fixture(t *testing.T, preparers ...FixturePreparer) Fixture {
Paul Duffindff5ff02021-03-15 15:42:40 +0000661 var buildDir string
662 if f.buildDirSupplier == nil {
663 // Create a new temporary directory for this run. It will be automatically cleaned up when the
664 // test finishes.
665 buildDir = t.TempDir()
666 } else {
667 // Retrieve the buildDir from the supplier.
668 buildDir = *f.buildDirSupplier
669 }
670 config := TestConfig(buildDir, nil, "", nil)
Paul Duffin35816122021-02-24 01:49:52 +0000671 ctx := NewTestContext(config)
672 fixture := &fixture{
Paul Duffincfd33742021-02-27 11:59:02 +0000673 factory: f,
674 t: t,
675 config: config,
676 ctx: ctx,
677 mockFS: make(MockFS),
678 errorHandler: f.errorHandler,
Paul Duffin35816122021-02-24 01:49:52 +0000679 }
680
681 for _, preparer := range f.preparers {
682 preparer.function(fixture)
683 }
684
685 for _, preparer := range dedupAndFlattenPreparers(f.preparers, preparers) {
686 preparer.function(fixture)
687 }
688
689 return fixture
690}
691
Paul Duffin46e37742021-03-09 11:55:20 +0000692func (f *fixtureFactory) ExtendWithErrorHandler(errorHandler FixtureErrorHandler) FixtureFactory {
Paul Duffin52323b52021-03-04 19:15:47 +0000693 newFactory := &fixtureFactory{}
694 *newFactory = *f
695 newFactory.errorHandler = errorHandler
696 return newFactory
Paul Duffincfd33742021-02-27 11:59:02 +0000697}
698
Paul Duffin35816122021-02-24 01:49:52 +0000699func (f *fixtureFactory) RunTest(t *testing.T, preparers ...FixturePreparer) *TestResult {
700 t.Helper()
701 fixture := f.Fixture(t, preparers...)
702 return fixture.RunTest()
703}
704
705func (f *fixtureFactory) RunTestWithBp(t *testing.T, bp string) *TestResult {
706 t.Helper()
707 return f.RunTest(t, FixtureWithRootAndroidBp(bp))
708}
709
Paul Duffin72018ad2021-03-04 19:36:49 +0000710func (f *fixtureFactory) RunTestWithConfig(t *testing.T, config Config) *TestResult {
711 t.Helper()
712 // Create the fixture as normal.
713 fixture := f.Fixture(t).(*fixture)
714
715 // Discard the mock filesystem as otherwise that will override the one in the config.
716 fixture.mockFS = nil
717
718 // Replace the config with the supplied one in the fixture.
719 fixture.config = config
720
721 // Ditto with config derived information in the TestContext.
722 ctx := fixture.ctx
723 ctx.config = config
724 ctx.SetFs(ctx.config.fs)
725 if ctx.config.mockBpList != "" {
726 ctx.SetModuleListFile(ctx.config.mockBpList)
727 }
728
729 return fixture.RunTest()
730}
731
Paul Duffin35816122021-02-24 01:49:52 +0000732type fixture struct {
Paul Duffincfd33742021-02-27 11:59:02 +0000733 // The factory used to create this fixture.
Paul Duffin35816122021-02-24 01:49:52 +0000734 factory *fixtureFactory
Paul Duffincfd33742021-02-27 11:59:02 +0000735
736 // The gotest state of the go test within which this was created.
737 t *testing.T
738
739 // The configuration prepared for this fixture.
740 config Config
741
742 // The test context prepared for this fixture.
743 ctx *TestContext
744
745 // The mock filesystem prepared for this fixture.
746 mockFS MockFS
747
748 // The error handler used to check the errors, if any, that are reported.
749 errorHandler FixtureErrorHandler
Paul Duffin35816122021-02-24 01:49:52 +0000750}
751
Paul Duffinae542a52021-03-09 03:15:28 +0000752func (f *fixture) Config() Config {
753 return f.config
754}
755
756func (f *fixture) Context() *TestContext {
757 return f.ctx
758}
759
760func (f *fixture) MockFS() MockFS {
761 return f.mockFS
762}
763
Paul Duffin35816122021-02-24 01:49:52 +0000764func (f *fixture) RunTest() *TestResult {
765 f.t.Helper()
766
767 ctx := f.ctx
768
Paul Duffin72018ad2021-03-04 19:36:49 +0000769 // Do not use the fixture's mockFS to initialize the config's mock file system if it has been
770 // cleared by RunTestWithConfig.
771 if f.mockFS != nil {
772 // The TestConfig() method assumes that the mock filesystem is available when creating so
773 // creates the mock file system immediately. Similarly, the NewTestContext(Config) method
774 // assumes that the supplied Config's FileSystem has been properly initialized before it is
775 // called and so it takes its own reference to the filesystem. However, fixtures create the
776 // Config and TestContext early so they can be modified by preparers at which time the mockFS
777 // has not been populated (because it too is modified by preparers). So, this reinitializes the
778 // Config and TestContext's FileSystem using the now populated mockFS.
779 f.config.mockFileSystem("", f.mockFS)
780
781 ctx.SetFs(ctx.config.fs)
782 if ctx.config.mockBpList != "" {
783 ctx.SetModuleListFile(ctx.config.mockBpList)
784 }
Paul Duffin35816122021-02-24 01:49:52 +0000785 }
786
787 ctx.Register()
Paul Duffin78c36212021-03-16 23:57:12 +0000788 var ninjaDeps []string
789 extraNinjaDeps, errs := ctx.ParseBlueprintsFiles("ignored")
Paul Duffincfd33742021-02-27 11:59:02 +0000790 if len(errs) == 0 {
Paul Duffin78c36212021-03-16 23:57:12 +0000791 ninjaDeps = append(ninjaDeps, extraNinjaDeps...)
792 extraNinjaDeps, errs = ctx.PrepareBuildActions(f.config)
793 if len(errs) == 0 {
794 ninjaDeps = append(ninjaDeps, extraNinjaDeps...)
795 }
Paul Duffincfd33742021-02-27 11:59:02 +0000796 }
Paul Duffin35816122021-02-24 01:49:52 +0000797
798 result := &TestResult{
Paul Duffin35816122021-02-24 01:49:52 +0000799 testContext: testContext{ctx},
800 fixture: f,
801 Config: f.config,
Paul Duffin942481b2021-03-04 18:58:11 +0000802 Errs: errs,
Paul Duffin78c36212021-03-16 23:57:12 +0000803 NinjaDeps: ninjaDeps,
Paul Duffin35816122021-02-24 01:49:52 +0000804 }
Paul Duffincfd33742021-02-27 11:59:02 +0000805
Paul Duffinc81854a2021-03-12 12:22:27 +0000806 f.errorHandler.CheckErrors(f.t, result)
Paul Duffincfd33742021-02-27 11:59:02 +0000807
Paul Duffin35816122021-02-24 01:49:52 +0000808 return result
809}
810
811// NormalizePathForTesting removes the test invocation specific build directory from the supplied
812// path.
813//
814// If the path is within the build directory (e.g. an OutputPath) then this returns the relative
815// path to avoid tests having to deal with the dynamically generated build directory.
816//
817// Otherwise, this returns the supplied path as it is almost certainly a source path that is
818// relative to the root of the source tree.
819//
820// Even though some information is removed from some paths and not others it should be possible to
821// differentiate between them by the paths themselves, e.g. output paths will likely include
822// ".intermediates" but source paths won't.
823func (r *TestResult) NormalizePathForTesting(path Path) string {
824 pathContext := PathContextForTesting(r.Config)
825 pathAsString := path.String()
826 if rel, isRel := MaybeRel(pathContext, r.Config.BuildDir(), pathAsString); isRel {
827 return rel
828 }
829 return pathAsString
830}
831
832// NormalizePathsForTesting normalizes each path in the supplied list and returns their normalized
833// forms.
834func (r *TestResult) NormalizePathsForTesting(paths Paths) []string {
835 var result []string
836 for _, path := range paths {
837 result = append(result, r.NormalizePathForTesting(path))
838 }
839 return result
840}
841
Paul Duffin35816122021-02-24 01:49:52 +0000842// Module returns the module with the specific name and of the specified variant.
843func (r *TestResult) Module(name string, variant string) Module {
844 return r.ModuleForTests(name, variant).Module()
845}