save cli
v0.3.10
Save est un cadre de test de ligne de commande tout usage qui peut être utilisé pour tester des outils qui fonctionnent avec du code, tels que les analyseurs statiques et les compilateurs. Il s'agit d'une application entièrement native, ne nécessitant pas besoin d'installer un SDK.
La vérification et l'évaluation de l'analyse statique (SAVE) est un écosystème (voir également Save-Cloud) conçu pour l'évaluation, les tests et la certification des analyseurs statiques, des compilateurs ou de tout autre outil logiciel. Au lieu de développer votre propre framework de test, vous pouvez utiliser une application de test en ligne de commande. La seule exigence consiste à préparer des ressources de test dans le format approprié.
Nous avons besoin de votre aide! Nous serons heureux si vous utilisez, testez ou contribuez à ce projet. Au cas où vous n'avez pas beaucoup de temps pour cela - au moins, donnez-nous une star pour attirer d'autres contributeurs! Merci! ?
- Mon outil d'analyse de code traite les fichiers séquentiellement, un par un ;
- Il produit des avertissements et les produit à STDOUT ;
- Je souhaite comparer les avertissements réels avec les avertissements attendus qui sont spécifiés dans le code de ressources de test .
- J'ai également un outil d'analyse de code, mais il traite l'ensemble du projet en même temps et est conscient de toutes les relations de code .;
- Il produit des avertissements et les produit à STDOUT ;
- Je souhaite comparer les avertissements réels avec les avertissements attendus qui sont spécifiés dans le code de ressources de test .
- Mon outil manipule le code d'origine, par exemple, en le fixant automatiquement;
- Je voudrais vérifier comment mon outil corrige le code en le comparant avec le résultat attendu;
- De plus, il peut être utilisé par les compilateurs pour valider la génération de code , passant de la source d'origine
- Code à la représentation intermédiaire (IR), un autre langage de programmation, ou même assemblage.
- Je ne veux pas spécifier mes avertissements attendus dans le code;
- Je préfère utiliser un fichier séparé dans Sarif ou tout autre format.
save "/my/path/to/tests" Assurez-vous que le répertoire tests contient le fichier de configuration save.toml .
Pour déboguer l'exécution de sauvegarde, vous pouvez utiliser l'argument suivant: --log=TYPE , où TYPE peut être l'un des éléments suivants:
all - journalisation complète qui inclut toutes les informations de l'exécution de sauvegarde, encore plus détaillées que le débogage (semblable à une trace).debug - Affiche les résultats, les avertissements et les informations de débogage.warnings - montre les résultats et les avertissements critiques.results_only - Affiche uniquement les résultats. 
Voici une liste de plugins standard:
Si vous souhaitez que plusieurs plugins fonctionnent dans votre répertoire en utilisant les mêmes fichiers de test (ressources), ajoutez-les simplement à la configuration save.toml :
[general]
...
[fix]
...
[warn]
...
[other plugin]
...
Vous pouvez en savoir plus sur le warn plugin ici
Save a une interface de ligne de commande qui vous permet d'exécuter à la fois le framework et votre exécutable. Votre tâche principale est de configurer la sortie de votre analyseur statique afin que SAVE puisse vérifier si l'erreur appropriée a été signalée sur la ligne correcte du code de test.
Pour s'assurer que l'avertissement est précis pour SAVE, votre analyseur statique doit sortir le résultat soit à stderr / stdout, soit un fichier journal désigné (par exemple au format Sarif).
Vous pouvez configurer le comportement général de Save à l'aide des arguments de ligne de commande ou en utilisant un fichier de configuration nommé save.properties . Ce fichier doit être situé dans le même répertoire que la configuration de test racine, save.toml .
Pour une liste complète d'options qui peuvent être transmises pour enregistrer via la ligne de commande ou le fichier save.properties , reportez-vous au tableau des options ou exécutez la commande save --help . Veuillez noter que les options avec les choix sont sensibles à la casse.
Le cadre de sauvegarde détectera automatiquement vos tests, exécutera votre analyseur sur eux, calculera la vitesse de réussite et les résultats des tests de retour dans le format attendu.
Pour activer Save pour détecter vos suites de test, vous devez placer un fichier save.toml dans chaque répertoire contenant des suites de test . Il est important de noter que ces fichiers de configuration héritent des configurations à partir des répertoires parents.
Bien que la plupart des champs puissent être laissés non définis à des niveaux inférieurs et peuvent hériter des valeurs des niveaux supérieurs, vous devez être prudent. Certains champs de la section [general] sont obligatoires pour l'exécution, vous devez donc les spécifier dans au moins un fichier de configuration dans la chaîne d'héritage pour les tests destinés à s'exécuter. Vérifiez quels champs sont obligatoires.
Par exemple, avec la hiérarchie du répertoire suivant:
| A
| save.toml
| B
| save.toml
Le save.toml dans le répertoire B héritera des paramètres et des propriétés du répertoire A.
Gardez à l'esprit que SAVE détectera tous les fichiers avec le «test» postfix et utilisera automatiquement les configurations à partir du fichier save.toml présent dans le même répertoire (ou hérité du parent). Les tests sont nommés selon le nom de ressource du fichier de test, à l'exclusion du suffixe «test». Si SAVE détecte un fichier avec le post-fixe «test» dans les ressources de test et ne peut localiser aucune configuration save.toml dans la hiérarchie du répertoire , elle lancera une erreur.
Par exemple, le scénario ci-dessous n'est pas valide et déclenchera une erreur, car le cadre de sauvegarde ne peut pas localiser le fichier de configuration save.toml :
| A
| B
| myTest.java
Comme mentionné précédemment, la save.toml est essentielle pour configurer des tests. Idéalement , il devrait y avoir un fichier de configuration pour chaque répertoire contenant des tests, établissant une relation un-à-plusieurs. Nous appelons ces répertoires comme test suites .
La justification derrière le fait d'avoir un seul fichier de configuration pour une suite de test est d'éviter les configurations redondantes dans la même suite de tests.
La configuration de sauvegarde utilise le format Toml alimenté par le projet KTOML. Comme mentionné ci-dessus, save.toml peut être hérité de la hiérarchie du répertoire (répertoires parents).
Le fichier de configuration contient une table [general] et une table [plugins] . Pour plus d'informations sur les plugins, reportez-vous à la section Plugins.
Dans cette section, nous fournirons des informations uniquement sur le tableau [general] , qui peut être utilisé sur tous les plugins.
[general]
# Your custom tags that will be used to detect groups of tests (required)
tags = ["parsing", "null-pointer", "etc"]
# Custom free text that describes the test suite (required)
description = "My suite description"
# Simple suite name (required)
suiteName = "DocsCheck", "CaseCheck", "NpeTests", "etc"
# Execution command (required at least once in the configuration hierarchy)
# By the default these binaries should be in the same directory of where SAVE is run
# or should have full or relational path (root - is the directory with save executable)
execCmd="./ktlint -R diktat-0.4.2.jar"
# Excluded tests in the suite (optional). Here, you can list the names of excluded tests, separated by commas. By default, no tests are excluded.
# To exclude tests, use the relative path to the root of the test project (to the root directory of `save.toml`)
excludedTests = ["warn/chapter1/GarbageTest.kt", "warn/otherDir/NewTest.kt", "etc"]
# Command execution time for one test (in milliseconds)
timeOutMillis = 10000
# Language for tests
language = "Kotlin"
Parfois, vous voudrez peut-être exécuter uniquement un ensemble spécifique de tests au lieu d'exécuter tous les tests sous une configuration save.toml particulière. Pour y parvenir, passez le chemin relatif au fichier de test après toutes les options de configuration (root - est répertoire avec Save Binary):
$ save [options] /path/to/tests/Test1Vous pouvez également fournir une liste de chemins relatifs pour tester les fichiers (séparés par des espaces):
$ save [options] /path/to/tests/Test1 /path/to/tests/Test2 Save détectera automatiquement le fichier save.toml le plus proche et utilise la configuration à partir de celui-ci.
Note: Sur Windows, n'oubliez pas d'utiliser un double backslash \ comme séparateur de chemin.
Enregistrer prend en charge plusieurs formats pour la sortie du rapport de test:
PLAIN : une table de type Markdown montrant tous les résultats des tests.PLAIN_FAILED : similaire à PLAIN , mais affiche uniquement les tests ratés.JSON : représentation structurée du résultat d'exécution. Le format souhaité peut être sélectionné à l'aide de l'option --report-type=PLAIN .
L'utilisation d'analyseurs statiques fait partie intégrante du processus de développement pour chaque produit logiciel. Bien que les développeurs de logiciels puissent rédiger divers tests et obtenir une bonne couverture de test, l'erreur humaine reste inévitable. Ces erreurs peuvent entraîner des pertes financières importantes pour les entreprises. L'analyse du programme statique aide à identifier et à rectifier des bogues et des problèmes qui pourraient ne pas être détectables grâce à des validations du compilateur seule.
L'analyse statique se présente sous diverses formes et sert différentes fins. Il pourrait impliquer une analyse simple utilisant un AST (abstrait de syntaxe) ou plonger dans des procédures plus complexes comme le CFA (analyse de flux de contrôle), une analyse interprocédurale ou une analyse contextuelle. Les analyseurs statiques peuvent évaluer le style de code, identifier les problèmes d'exécution potentiels dans la logique des applications, détecter les odeurs de code et suggérer les meilleures pratiques. Cependant, il reste un manque de clarté sur les fonctions centrales des analyseurs statiques. Comment leur efficacité peut-elle être quantifiée? Quels critères déterminent leur acceptation? Quelles fonctionnalités sont essentielles pour les développeurs qui créent un nouvel analyseur? Malgré des années de développement de l'analyseur statique, ces questions restent largement sans réponse.
Au début de leur parcours de développement, chaque créateur d'un analyseur statique commence par identifier les types de problèmes que leur outil ciblera. Cela nécessite souvent une recherche de listes existantes de problèmes potentiels ou de packages de test qui peuvent guider le processus de développement, en particulier si vous suivez une approche TDD (développement axé sur les tests). Alors que d'autres domaines de la programmation système ont établi des repères et des ensembles de tests, tels que les repères Spec.org utilisés à l'échelle mondiale pour évaluer divers composants logiciels et matériels, il n'existe pas de normes de ce type pour identifier les problèmes dans les langages de programmation populaires. Bien que les directives de codage en C / C ++ aient été établies par MISRA, il n'y a pas d'équivalents pour les langues largement utilisées comme Python et JVM. Il y a des suites de tests disponibles au NIST, mais leur cadre et leur écosystème sont quelque peu restrictifs.
Compte tenu de ce scénario, les développeurs se retrouvent souvent à recréer des mécanismes pour l'analyse statique ou le développement de nouveaux cadres de test, conduisant à un travail répétitif. Certains pourraient opter pour des directives existantes telles que les règles de style Google Code ou PMD, mais quelle que soit l'approche, un temps important est invariablement consacré à la conceptualisation, à l'écriture et à des tests de débogage.
Le projet utilise Gradle comme système de construction et peut être construit en utilisant la commande ./gradlew build .
Pour compiler des artefacts natifs, vous devez installer les conditions préalables comme décrit dans la documentation Kotlin / native.
Pour accéder aux dépendances hébergées sur le registre des packages GitHub, ajoutez ce qui suit à gradle.properties ou ~/.gradle/gradle.properties :
gprUser =<GH username>
gprKey =<GH personal access token> Un jeton d'accès personnel peut être généré sur https://github.com/settings/tokens/new. Assurez-vous que le jeton a une portée qui comprend read:packages
En raison du code généré, vous devez exécuter la version une fois pour importer correctement le projet dans un IDE avec des importations résolues.
