blob: 47dd8187266f0dcd4286b70a42b9ec5368df0ad5 [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),
231 }
232}
233
234// A set of mock files to add to the mock file system.
235type MockFS map[string][]byte
236
Paul Duffin6e9a4002021-03-11 19:01:26 +0000237// Merge adds the extra entries from the supplied map to this one.
238//
239// Fails if the supplied map files with the same paths are present in both of them.
Paul Duffin35816122021-02-24 01:49:52 +0000240func (fs MockFS) Merge(extra map[string][]byte) {
241 for p, c := range extra {
Paul Duffin80f4cea2021-03-16 14:08:00 +0000242 validateFixtureMockFSPath(p)
Paul Duffin6e9a4002021-03-11 19:01:26 +0000243 if _, ok := fs[p]; ok {
244 panic(fmt.Errorf("attempted to add file %s to the mock filesystem but it already exists", p))
245 }
Paul Duffin35816122021-02-24 01:49:52 +0000246 fs[p] = c
247 }
248}
249
Paul Duffin80f4cea2021-03-16 14:08:00 +0000250// Ensure that tests cannot add paths into the mock file system which would not be allowed in the
251// runtime, e.g. absolute paths, paths relative to the 'out/' directory.
252func validateFixtureMockFSPath(path string) {
253 // This uses validateSafePath rather than validatePath because the latter prevents adding files
254 // that include a $ but there are tests that allow files with a $ to be used, albeit only by
255 // globbing.
256 validatedPath, err := validateSafePath(path)
257 if err != nil {
258 panic(err)
259 }
260
261 // Make sure that the path is canonical.
262 if validatedPath != path {
263 panic(fmt.Errorf("path %q is not a canonical path, use %q instead", path, validatedPath))
264 }
265
266 if path == "out" || strings.HasPrefix(path, "out/") {
267 panic(fmt.Errorf("cannot add output path %q to the mock file system", path))
268 }
269}
270
Paul Duffin35816122021-02-24 01:49:52 +0000271func (fs MockFS) AddToFixture() FixturePreparer {
272 return FixtureMergeMockFs(fs)
273}
274
Paul Duffinae542a52021-03-09 03:15:28 +0000275// FixtureCustomPreparer allows for the modification of any aspect of the fixture.
276//
277// This should only be used if one of the other more specific preparers are not suitable.
278func FixtureCustomPreparer(mutator func(fixture Fixture)) FixturePreparer {
279 return newSimpleFixturePreparer(func(f *fixture) {
280 mutator(f)
281 })
282}
283
Paul Duffin35816122021-02-24 01:49:52 +0000284// Modify the config
285func FixtureModifyConfig(mutator func(config Config)) FixturePreparer {
286 return newSimpleFixturePreparer(func(f *fixture) {
287 mutator(f.config)
288 })
289}
290
291// Modify the config and context
292func FixtureModifyConfigAndContext(mutator func(config Config, ctx *TestContext)) FixturePreparer {
293 return newSimpleFixturePreparer(func(f *fixture) {
294 mutator(f.config, f.ctx)
295 })
296}
297
298// Modify the context
299func FixtureModifyContext(mutator func(ctx *TestContext)) FixturePreparer {
300 return newSimpleFixturePreparer(func(f *fixture) {
301 mutator(f.ctx)
302 })
303}
304
305func FixtureRegisterWithContext(registeringFunc func(ctx RegistrationContext)) FixturePreparer {
306 return FixtureModifyContext(func(ctx *TestContext) { registeringFunc(ctx) })
307}
308
309// Modify the mock filesystem
310func FixtureModifyMockFS(mutator func(fs MockFS)) FixturePreparer {
311 return newSimpleFixturePreparer(func(f *fixture) {
312 mutator(f.mockFS)
Paul Duffin80f4cea2021-03-16 14:08:00 +0000313
314 // Make sure that invalid paths were not added to the mock filesystem.
315 for p, _ := range f.mockFS {
316 validateFixtureMockFSPath(p)
317 }
Paul Duffin35816122021-02-24 01:49:52 +0000318 })
319}
320
321// Merge the supplied file system into the mock filesystem.
322//
323// Paths that already exist in the mock file system are overridden.
324func FixtureMergeMockFs(mockFS MockFS) FixturePreparer {
325 return FixtureModifyMockFS(func(fs MockFS) {
326 fs.Merge(mockFS)
327 })
328}
329
330// Add a file to the mock filesystem
Paul Duffin6e9a4002021-03-11 19:01:26 +0000331//
332// Fail if the filesystem already contains a file with that path, use FixtureOverrideFile instead.
Paul Duffin35816122021-02-24 01:49:52 +0000333func FixtureAddFile(path string, contents []byte) FixturePreparer {
334 return FixtureModifyMockFS(func(fs MockFS) {
Paul Duffin80f4cea2021-03-16 14:08:00 +0000335 validateFixtureMockFSPath(path)
Paul Duffin6e9a4002021-03-11 19:01:26 +0000336 if _, ok := fs[path]; ok {
337 panic(fmt.Errorf("attempted to add file %s to the mock filesystem but it already exists, use FixtureOverride*File instead", path))
338 }
Paul Duffin35816122021-02-24 01:49:52 +0000339 fs[path] = contents
340 })
341}
342
343// Add a text file to the mock filesystem
Paul Duffin6e9a4002021-03-11 19:01:26 +0000344//
345// Fail if the filesystem already contains a file with that path.
Paul Duffin35816122021-02-24 01:49:52 +0000346func FixtureAddTextFile(path string, contents string) FixturePreparer {
347 return FixtureAddFile(path, []byte(contents))
348}
349
Paul Duffin6e9a4002021-03-11 19:01:26 +0000350// Override a file in the mock filesystem
351//
352// If the file does not exist this behaves as FixtureAddFile.
353func FixtureOverrideFile(path string, contents []byte) FixturePreparer {
354 return FixtureModifyMockFS(func(fs MockFS) {
355 fs[path] = contents
356 })
357}
358
359// Override a text file in the mock filesystem
360//
361// If the file does not exist this behaves as FixtureAddTextFile.
362func FixtureOverrideTextFile(path string, contents string) FixturePreparer {
363 return FixtureOverrideFile(path, []byte(contents))
364}
365
Paul Duffin35816122021-02-24 01:49:52 +0000366// Add the root Android.bp file with the supplied contents.
367func FixtureWithRootAndroidBp(contents string) FixturePreparer {
368 return FixtureAddTextFile("Android.bp", contents)
369}
370
Paul Duffinbbccfcf2021-03-03 00:44:00 +0000371// Merge some environment variables into the fixture.
372func FixtureMergeEnv(env map[string]string) FixturePreparer {
373 return FixtureModifyConfig(func(config Config) {
374 for k, v := range env {
375 if k == "PATH" {
376 panic("Cannot set PATH environment variable")
377 }
378 config.env[k] = v
379 }
380 })
381}
382
383// Modify the env.
384//
385// Will panic if the mutator changes the PATH environment variable.
386func FixtureModifyEnv(mutator func(env map[string]string)) FixturePreparer {
387 return FixtureModifyConfig(func(config Config) {
388 oldPath := config.env["PATH"]
389 mutator(config.env)
390 newPath := config.env["PATH"]
391 if newPath != oldPath {
392 panic(fmt.Errorf("Cannot change PATH environment variable from %q to %q", oldPath, newPath))
393 }
394 })
395}
396
Paul Duffin2e0323d2021-03-04 15:11:01 +0000397// Allow access to the product variables when preparing the fixture.
398type FixtureProductVariables struct {
399 *productVariables
400}
401
402// Modify product variables.
403func FixtureModifyProductVariables(mutator func(variables FixtureProductVariables)) FixturePreparer {
404 return FixtureModifyConfig(func(config Config) {
405 productVariables := FixtureProductVariables{&config.productVariables}
406 mutator(productVariables)
407 })
408}
409
Paul Duffina560d5a2021-02-28 01:38:51 +0000410// GroupFixturePreparers creates a composite FixturePreparer that is equivalent to applying each of
411// the supplied FixturePreparer instances in order.
412//
413// Before preparing the fixture the list of preparers is flattened by replacing each
414// instance of GroupFixturePreparers with its contents.
415func GroupFixturePreparers(preparers ...FixturePreparer) FixturePreparer {
Paul Duffin35816122021-02-24 01:49:52 +0000416 return &compositeFixturePreparer{dedupAndFlattenPreparers(nil, preparers)}
417}
418
Paul Duffin50deaae2021-03-16 17:46:12 +0000419// NullFixturePreparer is a preparer that does nothing.
420var NullFixturePreparer = GroupFixturePreparers()
421
422// OptionalFixturePreparer will return the supplied preparer if it is non-nil, otherwise it will
423// return the NullFixturePreparer
424func OptionalFixturePreparer(preparer FixturePreparer) FixturePreparer {
425 if preparer == nil {
426 return NullFixturePreparer
427 } else {
428 return preparer
429 }
430}
431
Paul Duffin35816122021-02-24 01:49:52 +0000432type simpleFixturePreparerVisitor func(preparer *simpleFixturePreparer)
433
434// FixturePreparer is an opaque interface that can change a fixture.
435type FixturePreparer interface {
436 // visit calls the supplied visitor with each *simpleFixturePreparer instances in this preparer,
437 visit(simpleFixturePreparerVisitor)
438}
439
440type fixturePreparers []FixturePreparer
441
442func (f fixturePreparers) visit(visitor simpleFixturePreparerVisitor) {
443 for _, p := range f {
444 p.visit(visitor)
445 }
446}
447
448// dedupAndFlattenPreparers removes any duplicates and flattens any composite FixturePreparer
449// instances.
450//
451// base - a list of already flattened and deduped preparers that will be applied first before
452// the list of additional preparers. Any duplicates of these in the additional preparers
453// will be ignored.
454//
455// preparers - a list of additional unflattened, undeduped preparers that will be applied after the
456// base preparers.
457//
Paul Duffin59251822021-03-15 22:20:12 +0000458// Returns a deduped and flattened list of the preparers starting with the ones in base with any
459// additional ones from the preparers list added afterwards.
Paul Duffin35816122021-02-24 01:49:52 +0000460func dedupAndFlattenPreparers(base []*simpleFixturePreparer, preparers fixturePreparers) []*simpleFixturePreparer {
Paul Duffin59251822021-03-15 22:20:12 +0000461 if len(preparers) == 0 {
462 return base
463 }
464
465 list := make([]*simpleFixturePreparer, len(base))
Paul Duffin35816122021-02-24 01:49:52 +0000466 visited := make(map[*simpleFixturePreparer]struct{})
467
468 // Mark the already flattened and deduped preparers, if any, as having been seen so that
Paul Duffin59251822021-03-15 22:20:12 +0000469 // duplicates of these in the additional preparers will be discarded. Add them to the output
470 // list.
471 for i, s := range base {
Paul Duffin35816122021-02-24 01:49:52 +0000472 visited[s] = struct{}{}
Paul Duffin59251822021-03-15 22:20:12 +0000473 list[i] = s
Paul Duffin35816122021-02-24 01:49:52 +0000474 }
475
476 preparers.visit(func(preparer *simpleFixturePreparer) {
477 if _, seen := visited[preparer]; !seen {
478 visited[preparer] = struct{}{}
479 list = append(list, preparer)
480 }
481 })
482 return list
483}
484
485// compositeFixturePreparer is a FixturePreparer created from a list of fixture preparers.
486type compositeFixturePreparer struct {
487 preparers []*simpleFixturePreparer
488}
489
490func (c *compositeFixturePreparer) visit(visitor simpleFixturePreparerVisitor) {
491 for _, p := range c.preparers {
492 p.visit(visitor)
493 }
494}
495
496// simpleFixturePreparer is a FixturePreparer that applies a function to a fixture.
497type simpleFixturePreparer struct {
498 function func(fixture *fixture)
499}
500
501func (s *simpleFixturePreparer) visit(visitor simpleFixturePreparerVisitor) {
502 visitor(s)
503}
504
505func newSimpleFixturePreparer(preparer func(fixture *fixture)) FixturePreparer {
506 return &simpleFixturePreparer{function: preparer}
507}
508
Paul Duffincfd33742021-02-27 11:59:02 +0000509// FixtureErrorHandler determines how to respond to errors reported by the code under test.
510//
511// Some possible responses:
512// * Fail the test if any errors are reported, see FixtureExpectsNoErrors.
513// * Fail the test if at least one error that matches a pattern is not reported see
514// FixtureExpectsAtLeastOneErrorMatchingPattern
515// * Fail the test if any unexpected errors are reported.
516//
517// Although at the moment all the error handlers are implemented as simply a wrapper around a
518// function this is defined as an interface to allow future enhancements, e.g. provide different
519// ways other than patterns to match an error and to combine handlers together.
520type FixtureErrorHandler interface {
521 // CheckErrors checks the errors reported.
522 //
523 // The supplied result can be used to access the state of the code under test just as the main
524 // body of the test would but if any errors other than ones expected are reported the state may
525 // be indeterminate.
Paul Duffinc81854a2021-03-12 12:22:27 +0000526 CheckErrors(t *testing.T, result *TestResult)
Paul Duffincfd33742021-02-27 11:59:02 +0000527}
528
529type simpleErrorHandler struct {
Paul Duffinc81854a2021-03-12 12:22:27 +0000530 function func(t *testing.T, result *TestResult)
Paul Duffincfd33742021-02-27 11:59:02 +0000531}
532
Paul Duffinc81854a2021-03-12 12:22:27 +0000533func (h simpleErrorHandler) CheckErrors(t *testing.T, result *TestResult) {
534 t.Helper()
535 h.function(t, result)
Paul Duffincfd33742021-02-27 11:59:02 +0000536}
537
538// The default fixture error handler.
539//
540// Will fail the test immediately if any errors are reported.
Paul Duffinea8a3862021-03-04 17:58:33 +0000541//
542// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
543// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000544var FixtureExpectsNoErrors = FixtureCustomErrorHandler(
Paul Duffinc81854a2021-03-12 12:22:27 +0000545 func(t *testing.T, result *TestResult) {
546 t.Helper()
547 FailIfErrored(t, result.Errs)
Paul Duffincfd33742021-02-27 11:59:02 +0000548 },
549)
550
Paul Duffin85034e92021-03-17 00:20:34 +0000551// FixtureIgnoreErrors ignores any errors.
552//
553// If this is used then it is the responsibility of the test to check the TestResult.Errs does not
554// contain any unexpected errors.
555var FixtureIgnoreErrors = FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
556 // Ignore the errors
557})
558
Paul Duffincfd33742021-02-27 11:59:02 +0000559// FixtureExpectsAtLeastOneMatchingError returns an error handler that will cause the test to fail
560// if at least one error that matches the regular expression is not found.
561//
562// The test will be failed if:
563// * No errors are reported.
564// * One or more errors are reported but none match the pattern.
565//
566// The test will not fail if:
567// * Multiple errors are reported that do not match the pattern as long as one does match.
Paul Duffinea8a3862021-03-04 17:58:33 +0000568//
569// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
570// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000571func FixtureExpectsAtLeastOneErrorMatchingPattern(pattern string) FixtureErrorHandler {
Paul Duffinc81854a2021-03-12 12:22:27 +0000572 return FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
573 t.Helper()
574 if !FailIfNoMatchingErrors(t, pattern, result.Errs) {
575 t.FailNow()
Paul Duffinea8a3862021-03-04 17:58:33 +0000576 }
Paul Duffincfd33742021-02-27 11:59:02 +0000577 })
578}
579
580// FixtureExpectsOneErrorToMatchPerPattern returns an error handler that will cause the test to fail
581// if there are any unexpected errors.
582//
583// The test will be failed if:
584// * The number of errors reported does not exactly match the patterns.
585// * One or more of the reported errors do not match a pattern.
586// * No patterns are provided and one or more errors are reported.
587//
588// The test will not fail if:
589// * One or more of the patterns does not match an error.
Paul Duffinea8a3862021-03-04 17:58:33 +0000590//
591// If the test fails this handler will call `result.FailNow()` which will exit the goroutine within
592// which the test is being run which means that the RunTest() method will not return.
Paul Duffincfd33742021-02-27 11:59:02 +0000593func FixtureExpectsAllErrorsToMatchAPattern(patterns []string) FixtureErrorHandler {
Paul Duffinc81854a2021-03-12 12:22:27 +0000594 return FixtureCustomErrorHandler(func(t *testing.T, result *TestResult) {
595 t.Helper()
596 CheckErrorsAgainstExpectations(t, result.Errs, patterns)
Paul Duffincfd33742021-02-27 11:59:02 +0000597 })
598}
599
600// FixtureCustomErrorHandler creates a custom error handler
Paul Duffinc81854a2021-03-12 12:22:27 +0000601func FixtureCustomErrorHandler(function func(t *testing.T, result *TestResult)) FixtureErrorHandler {
Paul Duffincfd33742021-02-27 11:59:02 +0000602 return simpleErrorHandler{
603 function: function,
604 }
605}
606
Paul Duffin35816122021-02-24 01:49:52 +0000607// Fixture defines the test environment.
608type Fixture interface {
Paul Duffinae542a52021-03-09 03:15:28 +0000609 // Config returns the fixture's configuration.
610 Config() Config
611
612 // Context returns the fixture's test context.
613 Context() *TestContext
614
615 // MockFS returns the fixture's mock filesystem.
616 MockFS() MockFS
617
Paul Duffincfd33742021-02-27 11:59:02 +0000618 // Run the test, checking any errors reported and returning a TestResult instance.
Paul Duffin35816122021-02-24 01:49:52 +0000619 RunTest() *TestResult
620}
621
Paul Duffin35816122021-02-24 01:49:52 +0000622// Struct to allow TestResult to embed a *TestContext and allow call forwarding to its methods.
623type testContext struct {
624 *TestContext
625}
626
627// The result of running a test.
628type TestResult struct {
Paul Duffin35816122021-02-24 01:49:52 +0000629 testContext
630
631 fixture *fixture
632 Config Config
Paul Duffin942481b2021-03-04 18:58:11 +0000633
634 // The errors that were reported during the test.
635 Errs []error
Paul Duffin78c36212021-03-16 23:57:12 +0000636
637 // The ninja deps is a list of the ninja files dependencies that were added by the modules and
638 // singletons via the *.AddNinjaFileDeps() methods.
639 NinjaDeps []string
Paul Duffin35816122021-02-24 01:49:52 +0000640}
641
642var _ FixtureFactory = (*fixtureFactory)(nil)
643
644type fixtureFactory struct {
645 buildDirSupplier *string
646 preparers []*simpleFixturePreparer
647}
648
649func (f *fixtureFactory) Extend(preparers ...FixturePreparer) FixtureFactory {
Paul Duffin59251822021-03-15 22:20:12 +0000650 all := dedupAndFlattenPreparers(f.preparers, preparers)
651
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 }
Paul Duffin59251822021-03-15 22:20:12 +0000670
671 // Construct an array of all preparers, those from this factory and the additional ones passed to
672 // this method.
673 all := dedupAndFlattenPreparers(f.preparers, preparers)
674
Paul Duffindff5ff02021-03-15 15:42:40 +0000675 config := TestConfig(buildDir, nil, "", nil)
Paul Duffin35816122021-02-24 01:49:52 +0000676 ctx := NewTestContext(config)
677 fixture := &fixture{
Paul Duffincff464f2021-03-19 18:13:46 +0000678 preparers: all,
679 t: t,
680 config: config,
681 ctx: ctx,
682 mockFS: make(MockFS),
683 // Set the default error handler.
684 errorHandler: FixtureExpectsNoErrors,
Paul Duffin35816122021-02-24 01:49:52 +0000685 }
686
Paul Duffin59251822021-03-15 22:20:12 +0000687 for _, preparer := range all {
Paul Duffin35816122021-02-24 01:49:52 +0000688 preparer.function(fixture)
689 }
690
691 return fixture
692}
693
Paul Duffin46e37742021-03-09 11:55:20 +0000694func (f *fixtureFactory) ExtendWithErrorHandler(errorHandler FixtureErrorHandler) FixtureFactory {
Paul Duffincff464f2021-03-19 18:13:46 +0000695 return f.Extend(newSimpleFixturePreparer(func(fixture *fixture) {
696 fixture.errorHandler = errorHandler
697 }))
Paul Duffincfd33742021-02-27 11:59:02 +0000698}
699
Paul Duffin35816122021-02-24 01:49:52 +0000700func (f *fixtureFactory) RunTest(t *testing.T, preparers ...FixturePreparer) *TestResult {
701 t.Helper()
702 fixture := f.Fixture(t, preparers...)
703 return fixture.RunTest()
704}
705
706func (f *fixtureFactory) RunTestWithBp(t *testing.T, bp string) *TestResult {
707 t.Helper()
708 return f.RunTest(t, FixtureWithRootAndroidBp(bp))
709}
710
Paul Duffin72018ad2021-03-04 19:36:49 +0000711func (f *fixtureFactory) RunTestWithConfig(t *testing.T, config Config) *TestResult {
712 t.Helper()
713 // Create the fixture as normal.
714 fixture := f.Fixture(t).(*fixture)
715
716 // Discard the mock filesystem as otherwise that will override the one in the config.
717 fixture.mockFS = nil
718
719 // Replace the config with the supplied one in the fixture.
720 fixture.config = config
721
722 // Ditto with config derived information in the TestContext.
723 ctx := fixture.ctx
724 ctx.config = config
725 ctx.SetFs(ctx.config.fs)
726 if ctx.config.mockBpList != "" {
727 ctx.SetModuleListFile(ctx.config.mockBpList)
728 }
729
730 return fixture.RunTest()
731}
732
Paul Duffin35816122021-02-24 01:49:52 +0000733type fixture struct {
Paul Duffin59251822021-03-15 22:20:12 +0000734 // The preparers used to create this fixture.
735 preparers []*simpleFixturePreparer
Paul Duffincfd33742021-02-27 11:59:02 +0000736
737 // The gotest state of the go test within which this was created.
738 t *testing.T
739
740 // The configuration prepared for this fixture.
741 config Config
742
743 // The test context prepared for this fixture.
744 ctx *TestContext
745
746 // The mock filesystem prepared for this fixture.
747 mockFS MockFS
748
749 // The error handler used to check the errors, if any, that are reported.
750 errorHandler FixtureErrorHandler
Paul Duffin35816122021-02-24 01:49:52 +0000751}
752
Paul Duffinae542a52021-03-09 03:15:28 +0000753func (f *fixture) Config() Config {
754 return f.config
755}
756
757func (f *fixture) Context() *TestContext {
758 return f.ctx
759}
760
761func (f *fixture) MockFS() MockFS {
762 return f.mockFS
763}
764
Paul Duffin35816122021-02-24 01:49:52 +0000765func (f *fixture) RunTest() *TestResult {
766 f.t.Helper()
767
768 ctx := f.ctx
769
Paul Duffin72018ad2021-03-04 19:36:49 +0000770 // Do not use the fixture's mockFS to initialize the config's mock file system if it has been
771 // cleared by RunTestWithConfig.
772 if f.mockFS != nil {
773 // The TestConfig() method assumes that the mock filesystem is available when creating so
774 // creates the mock file system immediately. Similarly, the NewTestContext(Config) method
775 // assumes that the supplied Config's FileSystem has been properly initialized before it is
776 // called and so it takes its own reference to the filesystem. However, fixtures create the
777 // Config and TestContext early so they can be modified by preparers at which time the mockFS
778 // has not been populated (because it too is modified by preparers). So, this reinitializes the
779 // Config and TestContext's FileSystem using the now populated mockFS.
780 f.config.mockFileSystem("", f.mockFS)
781
782 ctx.SetFs(ctx.config.fs)
783 if ctx.config.mockBpList != "" {
784 ctx.SetModuleListFile(ctx.config.mockBpList)
785 }
Paul Duffin35816122021-02-24 01:49:52 +0000786 }
787
788 ctx.Register()
Paul Duffin78c36212021-03-16 23:57:12 +0000789 var ninjaDeps []string
790 extraNinjaDeps, errs := ctx.ParseBlueprintsFiles("ignored")
Paul Duffincfd33742021-02-27 11:59:02 +0000791 if len(errs) == 0 {
Paul Duffin78c36212021-03-16 23:57:12 +0000792 ninjaDeps = append(ninjaDeps, extraNinjaDeps...)
793 extraNinjaDeps, errs = ctx.PrepareBuildActions(f.config)
794 if len(errs) == 0 {
795 ninjaDeps = append(ninjaDeps, extraNinjaDeps...)
796 }
Paul Duffincfd33742021-02-27 11:59:02 +0000797 }
Paul Duffin35816122021-02-24 01:49:52 +0000798
799 result := &TestResult{
Paul Duffin35816122021-02-24 01:49:52 +0000800 testContext: testContext{ctx},
801 fixture: f,
802 Config: f.config,
Paul Duffin942481b2021-03-04 18:58:11 +0000803 Errs: errs,
Paul Duffin78c36212021-03-16 23:57:12 +0000804 NinjaDeps: ninjaDeps,
Paul Duffin35816122021-02-24 01:49:52 +0000805 }
Paul Duffincfd33742021-02-27 11:59:02 +0000806
Paul Duffinc81854a2021-03-12 12:22:27 +0000807 f.errorHandler.CheckErrors(f.t, result)
Paul Duffincfd33742021-02-27 11:59:02 +0000808
Paul Duffin35816122021-02-24 01:49:52 +0000809 return result
810}
811
812// NormalizePathForTesting removes the test invocation specific build directory from the supplied
813// path.
814//
815// If the path is within the build directory (e.g. an OutputPath) then this returns the relative
816// path to avoid tests having to deal with the dynamically generated build directory.
817//
818// Otherwise, this returns the supplied path as it is almost certainly a source path that is
819// relative to the root of the source tree.
820//
821// Even though some information is removed from some paths and not others it should be possible to
822// differentiate between them by the paths themselves, e.g. output paths will likely include
823// ".intermediates" but source paths won't.
824func (r *TestResult) NormalizePathForTesting(path Path) string {
825 pathContext := PathContextForTesting(r.Config)
826 pathAsString := path.String()
827 if rel, isRel := MaybeRel(pathContext, r.Config.BuildDir(), pathAsString); isRel {
828 return rel
829 }
830 return pathAsString
831}
832
833// NormalizePathsForTesting normalizes each path in the supplied list and returns their normalized
834// forms.
835func (r *TestResult) NormalizePathsForTesting(paths Paths) []string {
836 var result []string
837 for _, path := range paths {
838 result = append(result, r.NormalizePathForTesting(path))
839 }
840 return result
841}
842
Paul Duffin59251822021-03-15 22:20:12 +0000843// Preparer will return a FixturePreparer encapsulating all the preparers used to create the fixture
844// that produced this result.
845//
846// e.g. assuming that this result was created by running:
847// factory.Extend(preparer1, preparer2).RunTest(t, preparer3, preparer4)
848//
849// Then this method will be equivalent to running:
850// GroupFixturePreparers(preparer1, preparer2, preparer3, preparer4)
851//
852// This is intended for use by tests whose output is Android.bp files to verify that those files
853// are valid, e.g. tests of the snapshots produced by the sdk module type.
854func (r *TestResult) Preparer() FixturePreparer {
855 return &compositeFixturePreparer{r.fixture.preparers}
856}
857
Paul Duffin35816122021-02-24 01:49:52 +0000858// Module returns the module with the specific name and of the specified variant.
859func (r *TestResult) Module(name string, variant string) Module {
860 return r.ModuleForTests(name, variant).Module()
861}