Block Pre-Certification Checks Glossary

The purpose of this document is to provide the reader guidance, and examples, on how to
resolve the errors which are flagged by the Pre-Certification Checklists Analysis tool, that is
automatically run on all Merge Requests raised in a client project for building block development.
This document is owned and maintained by the BX Team.

⚠️ - please DO NOT delete the source branch which the pre-cert tool is triggered on
Frontend Blocks

Type of Check Criteria How to resolve

Builder Guidelines README.md is required with 1. A README.md should be present under

relevant information filled in or N/A
if not applicable
src/packages/blocks/BlockName
2. README should be updated with
description of the feature’s functionality and
instructions on the integration/setup
required to run the block in the project
3. Every heading and subheadings in the
README must be filled in

Builder Guidelines
All business logic must be in
controller files
1. View files should only contain render
functions that return JSX. Any functions
that contain setState, useState or react
lifecycle methods should be in the
corresponding controller files.
Type of Check Criteria How to resolve

Builder Guidelines Customisable area markers must

be present and located correctly

Builder Guidelines All network requests must be 1. There should not no use fetch, axios and
made using runEngine all network requests should be made
through runEngine

Builder Guidelines All css files must be removed 1. There must be no css, sass, scss or less
files under the src folder

Builder Guidelines All index.tsx files must be 1. There must be no index.tsx files under the
removed src folder

Builder Guidelines All navigation must be in 1. There should be no navigation logic inside
controller files the view

Builder Guidelines Snapshot unit testing is not 1. Remove all instances of

permitted in blocks code .toMatchSnapshot(...)
2. Remove all files with .snap extension

Builder Guidelines The config.json for the block must 1. Add all npm dependencies that the block
be correct requires to assembler-dependencies (in the
correct format - see other blocks for
examples)
Type of Check Criteria How to resolve

2. Add all npm dev dependencies that the

block requires to
assembler-devDependencies (in the
correct format - see other blocks for
examples)
3. Add all blocks that the block requires/is
dependent on, in catalog-dependencies
4. Add all screens that need to be added to
the navigator in assembler-exports
5. Ensure all the keys (see other blocks for
examples) are present in the config.json for
both mobile and web

Builder Guidelines Unit tests must be of a good
quality
1. Each ‘then’ block in the unit test should
have an expect inside it
2. Tests should be single responsibility (only
one expect statement inside each test)
3. Tests should not directly call functions on
the component e.g. instance.setState or
instance.doSomething()

Builder Guidelines There should be no hard coded
backend urls
1. Remove all references to hard coded
backend domains and just use the API
endpoint when sending requests through
RunEngine. RunEngine automatically uses
the backend domain from the environment
variables if no ‘http’ is included in the
network request
Type of Check Criteria How to resolve

Builder Guidelines There should be no .native.ts(x) 1. Use .web.tsx or .web.ts extensions when
extensions defining the platform for the file

Builder Guidelines 1. ​Check if the block’s code referencing any

There should no code referenced code outside of that particular block’s folder
which does not exist in the that is not part of the default Builder
boilerplate template application
2. Any code in the files highlighted by the
report must be moved to inside the block

Builder Guidelines 1. Remove usage of local storage from the

Async storage calls must be done controller
through RunEngine rather than 2. Remove any imports for async storage
directly accessing the async
storage or local storage APIs

Code Quality All variable names must be

descriptive and longer than 3
characters

Code Quality All commented code blocks must

be less than 5 lines and used
appropriately

Code Quality All console.log lines must be 1. Remove all console.log

removed

Code Quality Code must not interfere with 1. Remove all eslint_disable and ts-ignores
Typescript compilation or ES Lint
Type of Check Criteria
Code Quality Promise chaining must not be
used
Code Quality Types must be specified
File Structure Both Web and Mobile
implementation should be
developed for a Building Block
Metrics Test coverage must be a minimum
of 80% or above
This check differs from the pipeline
level unit_test check in that it tests if
the block’s config.json integrates
successfully with Code Engine in a
fresh project, and enables test
coverage to be collected on a fresh
React Native boilerplate when the
block is extracted and run in isolation.
If and only if the above is true, the
test coverage is checked to be 80%.
How to resolve
1. Remove all uses of .then() and .catch() in
your code and switch to using async await
and try {} catch (error) {}
1. All code must be strongly typed with
Typescript. No uses of the word ‘any’ are
allowed
1. Check if both .web.tsx and .tsx (mobile)
files are present for a building block - in
some cases, the feature may not be
compatible to build for both Web and
Mobile hence why this check will only be
flagged as a warning to start with
1. In most cases where a block’s
implementation uses a network js or npm
library, this check will execute.
2. In cases where the coverage is reported to
be low, you must search for “​​Running
test_coverage...” in the pre-certification
logs and address the errors listed for each
unit test one by one. E.g. ‘Cannot find
module 'x' from 'y'’ means module x is not
declared as a dependency in the block’s
config.json.
3. In cases where a block’s implementation is
very complex (i.e. requires changes to the
Frontend boilerplate code), this check will
fail to run with a “test_coverage
execution error”. You will still be able to
Type of Check Criteria How to resolve

see the test coverage on SonarQube

though and are encouraged to attach the
SQ and JEST output to the Tracker story
before sending through for certification.

Pre-cert Execution Error Block’s metadata must be
configured correctly (or npm
cache issues)
1. The config.json of the block must exist and
be configured correctly
a. All data must be in the correct
format (see other certified blocks for
examples) e.g.
assemblerDependencies,
assemblerDevDependencies,
catalogDependencies etc.
2. Check the logs of the pipeline to see if
there are any npm cache related errors - if
so retrigger the pipeline

Structural All new code must be in the src 1. Ensure that only the allowed files and
folder folders are in the root and that only new
code is in the src folder

Structural All class names must use

PascalCase

Structural All file names must be in Pascal

Case

Structural All file names must match class or

functional component names
Type of Check Criteria How to resolve

Structural There must be only one view per 1. E.g. iCalendarSupportController.tsx can
controller have either or both of iCalendarSupport.tsx
and iCalendarSupport.web.tsx. In
functional components, this equates to
iCalendarSupport.tsx (controller) to either
or both of iCalendarSupportView.tsx and
iCalendarSupportView.web.tsx
Backend Blocks
Report - Not Generated:
- Build failed for branch `BRANCH_NAME`. If the bundle install fails, the message will be sent instead of the table as MR
comment.

Type of Check Check name Criteria/description How to resolve

Invalid branch Make sure branch name follows the ● Verify building block name in branch
name pattern and includes Building Block name name

Bx/ActionName Make sure action names do not include Bad examples

HTTP verbs ● get_user
● delete_post
● transaction_get

Good examples
● view
● index

Bx/Association Make sure parent block does not have Bad and good examples
BlockDependen model association dependent on child
cy block

Bx/MigrationFil Make sure migration filenames end with Rename migration filename to include block suffix
ename a block name suffix
Bad examples
● 20221005143904_create_catalogu
e_variant_sizes.rb
● 20221005143904_bx_block_catalo
gue_create_catalogue_variant_s
izes.rb
 Good examples
● 20221005143904_create_catalogu
e_variant_sizes.bx_block_catal
ogue.rb
● 20221005143858_create_accounts
.account_block.rb
● 20221005143855_create_active_s
torage_tables.active_storage.r
b

Bx/MigrationSin Make sure migration modifies only tables Bad and good examples
gleBlock of Building Block specified in file name

Bx/ModelTable Make sure table names start with a block Go to a model and fix self.table_name
Name name using snake convention definition.

Rules Bad examples

● Table name must have a prefix.
● Table name must be in a plural
form.
● Table name must be in the snake
case.
favourites
Bx_block_favourites_favourites
Bx_block_favourites_favourite
Good examples
bx_block_favourites_favourites

File Structure Bx/Namespace Make sure controllers have all their Bad and good examples
dRoute endpoints under the same namespace

File Structure Bx/PathAndMo Make sure classes (models, controllers, Bad and good code examples
duleName services, helpers, and serializers) are
located in correct folders and have
correct module names.

Rules
 ● If a class has a Building Block in
its path, then it must have a
module with the name of the
Building Block.
● If a class has a module with a
Building Block, then it must have
the Building Block name in its
path.

File Structure Bx/SpecPresen Make sure classes (models, controllers, Bad and good examples
ce and services) are covered with tests.
Rules
● Model must have a spec
spec/models/<BX_BLOCK>/<
MODEL_NAME>_spec.rb
● Service must have a spec
spec/services/<BX_BLOCK>
/<SERVICE_NAME>_spec.rb
● Controller must have a spec
spec/api/<BX_BLOCK>/<MOD
EL_NAME>s_spec.rb

File Structure Bx/Swagger Make sure Bad and good examples

spec/swagger_helper.rb and
swagger/v1/swagger.json files
exist and they have correct format.

spec/swagger_helper.rb:
● info configuration has title,
version and description.
● openapi version is set to 3.0.1
 swagger/v1/swagger.json:

● All blocks’ endpoints exist in the

file.
● For each endpoint, there must be
at least one success example.
● For each endpoint, there must be
at least one fail example.
● For each endpoint, there must be
a schema and examples.

SonarQube Smells Make sure there are NO code smells Bad and good examples
reported by SonarQube in any files of the
client application's template app in
subdirectories named for the block in
question

SonarQube Bugs Make sure there are NO code bugs Bad and good examples
reported by SonarQube in any files of the
client application's template app in
subdirectories named for the block in
question

SonarQube Test Coverage Make sure test coverage of a Building Required minimum is 90%
Block meets minimal required level

Migrations Execution Ensure that the migrations for the

submitted code run successfully against
an empty database.
Migrations Existence Ensure that all models for the block have
migrations that create their table.

Migrations Schema of Determines that the schema for the

block block’s existing code exists (or can be
generated).
This only applies to block updates - not
for the creation of new blocks.

Migrations Only additions Ensure that migrations only add to the

existing schema - that it makes no
changes to other tables in the DB.
This only applies to block updates - not
for the creation of new blocks, and will
only run if the `Schema of Block` check
was successful.

Backend Blocks Code Examples

Bx/AssociationBlockDependency
Bad example Good example

module AccountBlock module BxBlockExpenses

class Account < class Expense <
AccountBlock::ApplicationRecord BxBlockExpenses::ApplicationRecord
has_many :expenses, class_name: belongs_to :budget, class_name:
"BxBlockExpenses::Expense", dependent: 'BxBlockExpenses::Budget', optional: true
:destroy end
end end
end
 module BxBlockExpenses
module PatchAccountExpensesAssociations
extend ActiveSupport::Concern
included do
has_many :expenses, class_name:
"BxBlockExpenses::Expense", dependent:
:destroy
end
end
end

Rails.application.reloader.to_prepare do
AccountBlock::Account.include(BxBlockExpenses:
:PatchAccountExpensesAssociations)
end

Bx/MigrationSingleBlock
Bad example Good example

# #
20230615055425_change_table_columns.bx_block_w 20230615055425_change_table_columns.bx_block_w
iki.rb iki.rb
class ChangeTableColumns < class ChangeTableColumns <
ActiveRecord::Migration[6.0] ActiveRecord::Migration[6.0]
def change def change
add_column :bx_block_catalogue_review, add_column :bx_block_wiki_pages, :version,
:version, :integer :integer
end end
end end
Bx/NamespacedRoute
Bad example Good example

# config/routes.rb # config/routes.rb
resources :referral_codes, only: :create namespace :bx_block_referrals do
resources :referral_codes, only: :create
# end
controllers/bx_block_referrals/referral_codes_
controller.rb #
module BxBlockReferrals controllers/bx_block_referrals/referral_codes_
class ReferralCodesController < controller.rb
ApplicationController module BxBlockReferrals
def create; end class ReferralCodesController <
end ApplicationController
end def create; end
end
end

# config/routes.rb
namespace :bx_block_wrong do
resources :referral_codes, only: :create
end

#
controllers/bx_block_referrals/referral_codes_
controller.rb
module BxBlockReferrals
class ReferralCodesController <
ApplicationController
def create; end
end
end

# config/routes.rb # config/routes.rb
namespace :bx_block_referrals do namespace :bx_block_referrals do
 patch :approve, to: 'referral_codes#approve' resources :referral_codes do
end member do
patch :approve
# end
controllers/bx_block_referrals/referral_codes_ end
controller.rb end
module BxBlockReferrals
class ReferralCodesController < #
ApplicationController controllers/bx_block_referrals/referral_codes_
def approve; end controller.rb
end module BxBlockReferrals
end class ReferralCodesController <
ApplicationController
def approve; end
end
end

Bx/PathAndModuleName
Bad example Good example

# app/models/bx_block_favourites/favourite.rb # app/models/bx_block_favourites/favourite.rb
class Favourite < ApplicationRecord; end module BxBlockFavourites
class Favourite < ApplicationRecord; end
end

# app/models/bx_block_favourites/favourite.rb # app/services/bx_block_sms/send_message.rb
module BxBlockExpenses module BxBlockSms
class Favourite < ApplicationRecord; end class SendMessage; end
end end

# app/services/providers/katrix.rb #
module BxBlockSms app/services/bx_block_sms/providers/katrix.rb
 module Providers module BxBlockSms
class Karix; end module Providers
end class Karix; end
end end
end

#
app/services/bx_block_sms/providers/katrix.rb
module Providers
class Karix; end
end

Bx/SpecPresence
Bad example Good example

app/models/bx_block_favourites/favourite.rb app/models/bx_block_favourites/favourite.rb
tested by tested by
spec/models/favourite_spec.rb spec/models/bx_block_favourites/favourite_spec
.rb

app/controllers/bx_block_favourites/favourites app/controllers/bx_block_favourites/favourites
_controller.rb _controller.rb
tested by tested by
spec/controllers/bx_block_favourites/favourite spec/api/bx_block_favourites/favourites_spec.r
s_controller_spec.rb b

app/controllers/bx_block_favourites/favourites app/services/bx_block_sms/provider_service.rb
_controller.rb tested by
tested by spec/services/bx_block_sms/provider_service_sp
spec/api/bx_block_favourites/favourites_contro ec.rb
ller_spec.rb

app/services/bx_block_sms/providers/katrix.rb
tested by
spec/services/bx_block_sms/providers/katrix_sp
ec.rb

Bx/Swagger
Bad example Good example

# spec/swagger_helper.rb file does not exist

# spec/swagger_helper.rb - incorrect output # spec/swagger_helper.rb

file config.swagger_docs = {
config.swagger_docs = { 'v1/swagger.json' => {
'v1/openapi.json' => { openapi: '3.0.1',
openapi: '3.0.1', info: {
info: { title: 'API title',
title: 'API title', version: 'v1',
version: 'v1', description: 'short description'
description: 'short description' },
}, paths: {},
paths: {}, components: {}
components: {} }
} }
}

# spec/swagger_helper.rb - missing description

config.swagger_docs = {
'v1/swagger.json' => {
openapi: '3.0.1',
info: {
 title: 'API title',
version: 'v1'
},
paths: {},
components: {}
}
}

# spec/swagger_helper.rb - missing info

attribute
config.swagger_docs = {
'v1/swagger.json' => {
openapi: '3.0.1',
paths: {},
components: {}
}
}

# spec/swagger_helper.rb - incorrect openapi

version
config.swagger_docs = {
'v1/swagger.json' => {
openapi: '2.0.1',
info: {
title: 'API title',
version: 'v1',
description: 'short description'
},
paths: {},
components: {}
}
}
Bx/SonarQube code smells
Bad example Good example

# #
controllers/bx_block_comments/comments_control controllers/bx_block_comments/comments_control
ler.rb ler.rb
module BxBlockComments module BxBlockComments
class CommentsController < class CommentsController <
ApplicationController ApplicationController

# method with no content would be a code # method with no content would be a code
smell smell
def archive;end def archive
end # adding even a comment should remove
end the ‘smell’
end
end
end

Bx/SonarQube code bugs

Bad example Good example

# #
controllers/bx_block_comments/comments_control controllers/bx_block_comments/comments_control
ler.rb ler.rb
module BxBlockComments module BxBlockComments
class CommentsController < class CommentsController <
ApplicationController ApplicationController

# method with no content would be a code # method with no content would be a code
smell smell
def archive def archive
return false if "this can never get reached" == true
 if "this can never get reached" == true return false
# do some stuff else
end return false
end end
end end
end end
end