Create The Scope
Access the Kotlin files using Konsist API
Last updated
Access the Kotlin files using Konsist API
Last updated
Scope represents a set of Kotlin files to be further queried, filtered (Declaration Filtering), and verified (Declaration Assertion).
Every scope contains a set of KoFile instances. Every KoFile instance contains the declarations (see Declaration) representing code entities present in the file e.g.:
The scope can be created for an entire project, module, package, and Kotlin file.
The scope is dynamically built based on the Kotlin files present in the project, enabling it to adapt seamlessly as the project evolves. For instance, when the scope is set to encapsulate a specific module, any additional file introduced to that module will be automatically incorporated into the scope. This ensures that the scope consistently offers thorough and current coverage.
To execute Konsist tests, the Konsist dependency must be integrated into a module. Yet, by integrating Konsist into a single module (e.g. app module), Konsist can still access the entire project. The specific files evaluated are determined by the evolving scope that's been defined.
Various methods can be used to obtain instances of the scope. This allows the definition of more granular Konsist tests e.g. tests covering only certain modules, source sets, packages, or folders.
The widest scope is the scope containing all Kotlin files present inside the project:
To print a list of files within koScope use the koScope.print() method:
The scopeFromProduction method allows the creation of a scope containing only a production code (equivalent to Konsist.scopeFromProject() - Konsist.scopeFromTest()):
Contains:
The scopeFromTest method allows the creation of a scope containing only a test code:
Contains:
The scopeFromModule method allows the creation of more granular scopes based on the module name e.g. creating a scope containing all Kotlin files present in the app module:
Contains:
This approach may be helpful when refactoring existing project modules by module.
A nested module is a module that exists within another module.
The nested modules the feature is not complete. The community is reporting that this feature works, however, we still have to take a closer look, review expectations, and add tests. Consider this feature as experimental for now.
Consider this feature module existing inside app module:
To narrow the scope to feature module use:
The scopeFromSourceSet method argument allows the creation of more granular scopes based on the source set name e.g. create a scope containing all Kotlin files present in the test source set:
Contains:
To retrieve scope by using both module and source set use the scopeFromProject method with moduleName and sourceSetName arguments:
Contains:
The sourceFromPackage method allows the creation of a scope containing code present in a given package e.g. com.usecase package:
Contains:
The scopeFromDirectory method allows the creation of a scope containing code present in a given project folder e.g. domain directory:
Contains:
It is also possible to create scope from one or more file paths:
We have added a new way of creating the scope from a list of files. This can help with certain development workflows e.g. runing Konsist Tests only on files modified in a given PR:
For even more granular control you can use the KoScope.slice method to retrieve a scope containing a subset of files from the given scope:
The KoScope can be printed to display a list of all files present in the scope. Here is an example:
To reuse scope across the test class define the scope in the companion object and access it from multiple tests:
To reuse scope across the multiple test classes define the scope in the file and access it from multiple test classes:
Here is the file structure representing the above snippet:
Scope subtraction is also supported, so it is possible for example to exclude a part of a given module. Here scope is created from myFeature module and then the ..data.. package is excluded:
To print all files within the scope use the print() method:
To access specific declaration types such as interfaces, classes, constructors, functions, etc. utilize the Declaration Filtering.
Konsist scope supports , so scopes can be further combined together to create the desired scope, tailored to project needs. In this example scopes from myFeature1 module and myFeature2 module are combined together: